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

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 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. 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 to load the generated specification. This function reads the authoritative spec from 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. The integration logic supports three distinct output modes:

• Default mode: Outputs only the spec content from 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:

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:

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:

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:

# 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 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, while --rulesOnly isolates the rules table.
• This command eliminates drift between agent behavior and the evolving DESIGN.md format by treating 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 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 using the getSpecContent() function defined in src/linter/spec-gen/spec-helpers.js. This file contains the generated, authoritative format definition.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}