# What Is the spec Command in DESIGN.md and How to Use It for Agent Prompts

> Learn how to use the spec command in DESIGN.md to generate compliant design documents. This CLI tool provides the schema, ordering, and linting rules for AI agents.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-07-03

---

**The `spec` command is a CLI tool that outputs the authoritative DESIGN.md format specification in Markdown or JSON, enabling AI agents to generate compliant design documents by consuming the schema, section ordering, and linting rules at runtime.**

The `spec` command in the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository provides runtime access to the complete DESIGN.md format specification. By exposing the exact schema, token definitions, and active linting rules through a command-line interface, it functions as the single source of truth for both human developers and automated agents.

## Purpose of the spec Command in DESIGN.md

The primary purpose of the `spec` command is to eliminate hard-coded assumptions about the DESIGN.md format. Rather than embedding schema definitions within agent code or documentation, tools can query the specification dynamically at runtime.

This approach ensures that agents always reference the current version of the format, including precise section ordering, front-matter delimiters, and token naming conventions. The command supports multiple output formats—plain Markdown for human readability and structured JSON for programmatic consumption—making it adaptable to various agent architectures.

## Architecture and Implementation

### Command Definition

The CLI sub-command is implemented in [`packages/cli/src/commands/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/spec.ts). This module handles argument parsing and delegates content retrieval to specialized helper functions.

### Content Loading

The command utilizes `getSpecContent()` from [`src/linter/spec-gen/spec-helpers.js`](https://github.com/google-labs-code/design.md/blob/main/src/linter/spec-gen/spec-helpers.js) to load the generated specification. This function reads the authoritative spec from [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md), which contains the complete schema definition, section hierarchies, and formatting rules.

### Rule Integration

To provide visibility into validation constraints, the command invokes `getRulesTable()`, which renders descriptors from `DEFAULT_RULE_DESCRIPTORS` exported by [`src/linter/linter/rules/index.js`](https://github.com/google-labs-code/design.md/blob/main/src/linter/linter/rules/index.js). The integration logic supports three distinct output modes:

- **Default mode**: Outputs only the spec content from [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md).
- **Rules appending**: When `--rules` is supplied, the command appends the active linting rules table under an `## Active Linting Rules` heading.

- **Rules only**: When `--rulesOnly` is supplied, the command emits exclusively the linting rules table without the spec content.

## Using the spec Command for Agent Prompts

AI agents can consume the `spec` command output to ensure generated DESIGN.md files comply with the current format standard. Three primary usage patterns enable this integration.

### Fetching the Spec as JSON

For agents that parse specifications programmatically, output the spec as JSON:

```bash
design-cli spec --format json > design-spec.json

```

The resulting file can be loaded into the agent's system context, providing structured access to section requirements, token schemas, and validation rules.

### Embedding Raw Markdown Directly

To inject the specification directly into an agent's prompt context, pipe the Markdown output:

```bash
design-cli spec --format markdown | \
your-agent-cli --system-prompt "$(cat -)"

```

This method ensures the agent receives the exact section ordering and delimiter syntax required for compliant document generation.

### Including Active Linting Rules

Adding the `--rules` flag provides agents with immediate visibility into enforcement constraints:

```bash
design-cli spec --rules > full-spec.md

```

This outputs both the format specification and the active linting rules, allowing agents to pre-validate content and avoid common violations without requiring a separate linting pass.

## CLI Reference and Examples

The following commands demonstrate the complete functionality of the `spec` command:

```bash

# Print the spec as markdown (default)

design-cli spec

# Print the spec as JSON for programmatic consumption

design-cli spec --format json > spec.json

# Output only the active linting rules (markdown table)

design-cli spec --rulesOnly

# Output spec + linting rules (useful for prompting agents)

design-cli spec --rules > full-spec.md

# Use the JSON spec as a system prompt for an LLM agent

cat spec.json | your-agent --system-prompt "$(cat -)"

```

## Summary

- The `spec` command in [`packages/cli/src/commands/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/spec.ts) exposes the DESIGN.md format specification at runtime via `getSpecContent()` and `getRulesTable()`.
- It supports `--format json` for structured data and default Markdown for human-readable output.
- Agents can consume the spec via `design-cli spec --format json` to obtain the schema programmatically.
- The `--rules` flag appends active linting rules from [`src/linter/linter/rules/index.js`](https://github.com/google-labs-code/design.md/blob/main/src/linter/linter/rules/index.js), while `--rulesOnly` isolates the rules table.
- This command eliminates drift between agent behavior and the evolving DESIGN.md format by treating [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) as the single source of truth.

## Frequently Asked Questions

### What does the spec command output by default?

By default, the `spec` command outputs the complete DESIGN.md format specification in Markdown format, loaded from [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) via the `getSpecContent()` function.

### How can I extract only the linting rules without the full specification?

Use the `--rulesOnly` flag. This invokes `getRulesTable()` to render only the active linting rule descriptors from `DEFAULT_RULE_DESCRIPTORS` without including the main specification content.

### Can the spec command output be used directly as an LLM system prompt?

Yes. You can pipe the Markdown output directly to an agent's system prompt parameter, or load the JSON output into the agent's context. This ensures the LLM receives the exact schema, section ordering, and token definitions required to generate compliant DESIGN.md files.

### Where does the spec command load the specification from?

The command loads the specification from [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) using the `getSpecContent()` function defined in [`src/linter/spec-gen/spec-helpers.js`](https://github.com/google-labs-code/design.md/blob/main/src/linter/spec-gen/spec-helpers.js). This file contains the generated, authoritative format definition.