Add Document Type Definitions (DTD) support for job outputs

Implement DTDs as a first-class feature for formalizing document specifications
with quality criteria, enabling consistent document structure across job outputs.

Key changes:
- Add DTD schema and parser for frontmatter markdown format
- Extend job.yml output schema to support DTD references
- Update skill generators to inject DTD context into templates
- Add document detection workflow to deepwork_jobs.define
- Add DTD improvement workflow to deepwork_jobs.learn
- Update Claude and Gemini templates for DTD-aware rendering
- Bump version to 0.4.0

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: nhorton

CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to DeepWork will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-01-20
+
+### Added
+- Document Type Definitions (DTDs) as a first-class feature for formalizing document specifications
+  - New `src/deepwork/schemas/dtd_schema.py` with JSON schema validation
+  - New `src/deepwork/core/dtd_parser.py` with parser for frontmatter markdown DTD files
+  - DTD files stored in `.deepwork/dtds/` directory with quality criteria and example documents
+  - Auto-creates `.deepwork/dtds/` directory during `deepwork install`
+- Extended job.yml output schema to support DTD references
+  - Outputs can now be strings (backward compatible) or objects with `file` and optional `dtd` fields
+  - Example: `outputs: [{file: "report.md", dtd: "monthly_report"}]`
+- DTD-aware skill generation
+  - Step skills now include DTD quality criteria, target audience, and example documents
+  - Both Claude and Gemini templates updated for DTD rendering
+- Document detection workflow in `deepwork_jobs.define`
+  - Steps 1.5, 1.6, 1.7 guide users through creating DTDs for document-oriented jobs
+  - Pattern indicators: "report", "summary", "create", "monthly", "for stakeholders"
+- DTD improvement workflow in `deepwork_jobs.learn`
+  - Steps 3.5, 4.5 capture DTD-related learnings and update DTD files
+- New `OutputSpec` dataclass in parser for structured output handling
+- Comprehensive DTD documentation in `doc/document-type-definitions.md`
+- New test fixtures for DTD validation and parsing
+
+### Changed
+- `Step.outputs` changed from `list[str]` to `list[OutputSpec]` for richer output metadata
+- `SkillGenerator.generate_all_skills()` now accepts `project_root` parameter for DTD loading
+- Updated `deepwork_jobs` to v0.6.0 with DTD-related quality criteria
+
 ## [0.3.0] - 2026-01-18
 
 ### Added
@@ -100,6 +128,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Initial version.
 
+[0.4.0]: https://github.com/anthropics/deepwork/releases/tag/0.4.0
 [0.3.0]: https://github.com/anthropics/deepwork/releases/tag/0.3.0
 [0.1.1]: https://github.com/anthropics/deepwork/releases/tag/0.1.1
 [0.1.0]: https://github.com/anthropics/deepwork/releases/tag/0.1.0

README.md

@@ -200,6 +200,7 @@ your-project/
 ## Documentation
 
 - **[Architecture](doc/architecture.md)**: Complete design specification
+- **[Document Type Definitions](doc/document-type-definitions.md)**: DTD format for output quality criteria
 - **[Contributing](CONTRIBUTING.md)**: Setup development environment and contribute
 
 ## Project Structure
@@ -241,6 +242,7 @@ Define structured, multi-step workflows where each step has clear requirements a
 - **Artifact Passing**: Seamlessly use file outputs from one step as inputs for future steps.
 - **Dynamic Inputs**: Support for both fixed file references and interactive user parameters.
 - **Human-Readable YAML**: Simple, declarative job definitions that are easy to version and maintain.
+- **Document Type Definitions**: Reference DTDs to enforce quality criteria on document outputs (see [DTD documentation](doc/document-type-definitions.md)).
 
 ### Git-Native Workflow
 Maintain a clean repository with automatic branch management and isolation.

doc/architecture.md

@@ -46,6 +46,7 @@ deepwork/                       # DeepWork tool repository
 │       │   ├── detector.py     # AI platform detection
 │       │   ├── generator.py    # Command file generation
 │       │   ├── parser.py       # Job definition parsing
+│       │   ├── dtd_parser.py   # Document Type Definition parsing
 │       │   ├── rules_parser.py     # Rule definition parsing
 │       │   ├── pattern_matcher.py  # Variable pattern matching for rules
 │       │   ├── rules_queue.py      # Rule state queue system
@@ -65,7 +66,10 @@ deepwork/                       # DeepWork tool repository
 │       ├── standard_jobs/      # Built-in job definitions
 │       │   ├── deepwork_jobs/
 │       │   │   ├── job.yml
-│       │   │   └── steps/
+│       │   │   ├── steps/
+│       │   │   └── templates/
+│       │   │       ├── dtd.md.template
+│       │   │       └── dtd.md.example
 │       │   └── deepwork_rules/   # Rule management job
 │       │       ├── job.yml
 │       │       ├── steps/
@@ -76,6 +80,7 @@ deepwork/                       # DeepWork tool repository
 │       │           └── capture_prompt_work_tree.sh
 │       ├── schemas/            # Definition schemas
 │       │   ├── job_schema.py
+│       │   ├── dtd_schema.py   # DTD schema definition
 │       │   └── rules_schema.py
 │       └── utils/
 │           ├── fs.py
@@ -290,6 +295,8 @@ my-project/                     # User's project (target)
 ├── .deepwork/                  # DeepWork configuration
 │   ├── config.yml              # Platform config
 │   ├── .gitignore              # Ignores tmp/ directory
+│   ├── dtds/                   # Document Type Definitions
+│   │   └── monthly_aws_report.md
 │   ├── rules/                  # Rule definitions (v2 format)
 │   │   ├── source-test-pairing.md
 │   │   ├── format-python.md
@@ -1190,6 +1197,90 @@ def my_hook(input: HookInput) -> HookOutput:
 
 See `doc/platforms/` for detailed platform-specific hook documentation.
 
+---
+
+## Document Type Definitions (DTDs)
+
+Document Type Definitions (DTDs) formalize document specifications for job outputs. They enable consistent document structure and automated quality validation.
+
+### Purpose
+
+DTDs solve a common problem with AI-generated documents: inconsistent quality and structure. By defining:
+- Required quality criteria
+- Target audience
+- Document structure (via example)
+
+DTDs ensure that documents produced by job steps meet consistent standards.
+
+### DTD File Format
+
+DTDs are stored in `.deepwork/dtds/[dtd_name].md` using frontmatter markdown:
+
+```markdown
+---
+name: "Monthly AWS Spending Report"
+description: "A Markdown summary of AWS spend across accounts"
+path_patterns:
+  - "finance/aws-reports/*.md"
+target_audience: "Finance team and Engineering leadership"
+frequency: "Monthly, following AWS invoice arrival"
+quality_criteria:
+  - name: Visualization
+    description: Must include Mermaid.js charts showing spend per service
+  - name: Variance Analysis
+    description: Must compare current month against previous with percentages
+---
+
+# Monthly AWS Spending Report: [Month, Year]
+
+## Executive Summary
+[Example content...]
+```
+
+### Using DTDs in Jobs
+
+Reference DTDs in job.yml outputs:
+
+```yaml
+outputs:
+  - file: reports/monthly_spending.md
+    dtd: monthly_aws_report  # References .deepwork/dtds/monthly_aws_report.md
+```
+
+### Generated Skills
+
+When `deepwork sync` runs, skills with DTD-referenced outputs include:
+- Document name and description
+- Target audience
+- All quality criteria with descriptions
+- Example document structure (collapsible)
+
+### DTD Schema
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Human-readable document name |
+| `description` | Yes | Purpose of the document |
+| `quality_criteria` | Yes | Array of `{name, description}` quality requirements |
+| `path_patterns` | No | Where documents should be stored |
+| `target_audience` | No | Who reads the document |
+| `frequency` | No | How often produced |
+
+### Workflow Integration
+
+The `/deepwork_jobs.define` command:
+1. Detects document-oriented workflows (keywords: "report", "summary", "monthly")
+2. Guides users through DTD creation
+3. Links DTDs to job outputs
+
+The `/deepwork_jobs.learn` command:
+1. Identifies DTD-related learnings (quality criteria issues, structure changes)
+2. Updates DTD files with improvements
+
+See `doc/document-type-definitions.md` for complete documentation.
+
+---
+
 ### Rule Schema
 
 Rules are validated against a JSON Schema: