feat: DeepSchema system for rich file schemas

.deepwork/review/suggest_new_reviews.md

@@ -1,24 +1,34 @@
-# Suggest New Review Rules
+# Suggest New Review Rules and DeepSchemas
 
-You are reviewing a changeset to determine whether any new DeepWork review rules should be added to catch issues found in these changes going forward.
+You are reviewing a changeset to determine whether any new DeepWork review rules or DeepSchemas should be added to catch issues found in these changes going forward.
+
+## Two enforcement mechanisms
+
+1. **`.deepreview` rules** — review rules that run during `/review` and quality gates. Best for cross-file checks, process enforcement, and subjective quality criteria.
+2. **DeepSchemas** — rich file-level schemas (`.deepwork/schemas/<name>/deepschema.yml` for named, `.deepschema.<filename>.yml` for anonymous). Best for per-file structural requirements, JSON Schema validation, and bash verification commands. DeepSchemas automatically generate review rules AND provide write-time validation hooks.
+
+Use DeepSchemas when the issue is about a specific file type having structural or content requirements. Use `.deepreview` rules when the issue is about cross-file consistency, process adherence, or subjective review.
 
 ## Steps
 
-1. **Get current rules**: Call `mcp__plugin_deepwork_deepwork__get_configured_reviews` to see all currently configured review rules. Understand what's already covered.
+1. **Get current rules and schemas**: Call `mcp__plugin_deepwork_deepwork__get_configured_reviews` to see all currently configured review rules (including DeepSchema-generated ones). Also call `mcp__plugin_deepwork_deepwork__get_named_schemas` to see existing DeepSchemas. Understand what's already covered.
 
 2. **Read the reviews README**: Read `@README_REVIEWS.md` (in the repository root) to understand the full range of review capabilities and rule structures.
 
 3. **Analyze the changeset**: Look at all the changed files. For each change, consider:
-   - Did this change introduce a type of issue that a review rule could catch?
+   - Did this change introduce a type of issue that a review rule or DeepSchema could catch?
    - Is there a pattern here that's likely to recur?
    - Would an existing rule benefit from a small scope expansion to cover a new file type?
+   - Is there a file type that would benefit from a DeepSchema (structural requirements, JSON Schema, or bash verification)?
 
-4. **Write new rules directly**: For each rule you decide to create:
-   - If it's a **new rule**: add it to the appropriate `.deepreview` file with full YAML
+4. **Write new rules or schemas directly**: For each rule you decide to create:
+   - If it's a **new `.deepreview` rule**: add it to the appropriate `.deepreview` file with full YAML
    - If it's an **addition to an existing rule's `include` list**: edit the existing rule in-place
    - If the rule needs a dedicated instruction file: create it in `.deepwork/review/`
+   - If it's a **new named DeepSchema**: create `.deepwork/schemas/<name>/deepschema.yml` with `summary`, `matchers`, and `requirements`
+   - If it's a **new anonymous DeepSchema**: create `.deepschema.<filename>.yml` next to the target file
 
-5. **Output**: After writing rules to their files, list each new rule or modification you made, with just its name and description. This summary is your final report.
+5. **Output**: After writing rules/schemas to their files, list each new rule or schema you created, with just its name and description. This summary is your final report.
 
 ## CRITICAL: Be Extremely Conservative
 

.gitignore

@@ -67,6 +67,9 @@ dmypy.json
 *~
 .DS_Store
 
+# Claude Code
+.claude/worktrees/
+
 # direnv
 .direnv/
 

AGENTS.md

@@ -193,12 +193,14 @@ deepwork/
 │   ├── core/             # Core logic (doc_spec_parser)
 │   ├── jobs/             # Job discovery, parsing, schema, and MCP server
 │   │   └── mcp/          # MCP server module (the core runtime)
+│   ├── deepschema/       # DeepSchema subsystem (config, discovery, matcher, resolver, review_bridge, schema)
 │   ├── hooks/            # Hook scripts and wrappers
 │   ├── standard_jobs/    # Built-in job definitions (auto-discovered at runtime)
 │   │   ├── deepwork_jobs/
 │   │   └── deepwork_reviews/
+│   ├── standard_schemas/ # Built-in DeepSchema definitions
 │   ├── review/           # DeepWork Reviews system (.deepreview pipeline)
-│   ├── schemas/          # Definition schemas (deepreview, doc_spec)
+│   ├── schemas/          # Definition schemas (deepreview, deepschema, doc_spec)
 │   └── utils/            # Utilities (fs, git, yaml, validation)
 ├── platform/             # Shared platform-agnostic content
 │   └── skill-body.md     # Canonical skill body (source of truth)
@@ -210,8 +212,9 @@ deepwork/
 │   │   ├── skills/
 │   │   │   ├── configure_reviews/SKILL.md
 │   │   │   ├── deepwork/SKILL.md
+│   │   │   ├── deepschema/SKILL.md
 │   │   │   └── review/SKILL.md
-│   │   ├── hooks/        # hooks.json, post_commit_reminder.sh, post_compact.sh, startup_context.sh
+│   │   ├── hooks/        # hooks.json, post_commit_reminder.sh, post_compact.sh, startup_context.sh, deepschema_write.sh
 │   │   └── .mcp.json     # MCP server config
 │   └── gemini/           # Gemini CLI extension
 │       └── skills/deepwork/SKILL.md

README.md

@@ -187,7 +187,7 @@ Similar to how vibe coding makes it easier for anyone to produce software, this
 
 ## DeepWork Reviews — Deep Dive
 
-Reviews are `.deepreview` config files placed anywhere in your project, scoped to the directory they live in (like `.gitignore`). When you run a review, it diffs your branch, matches changed files against your rules, and dispatches parallel AI review agents.
+Reviews are `.deepreview` config files placed anywhere in your project, scoped to the directory they live in (like `.gitignore`). DeepSchemas (in `.deepwork/schemas/`) also generate synthetic review rules automatically. When you run a review, it diffs your branch, matches changed files against your rules (from both `.deepreview` files and DeepSchemas), and dispatches parallel AI review agents.
 
 ### Why This Is Powerful
 
@@ -275,6 +275,40 @@ See [README_REVIEWS.md](README_REVIEWS.md) for the full reference — strategies
 
 ---
 
+## DeepSchemas — File-Level Schemas
+
+DeepSchemas are rich, file-level schemas that give both humans and AI agents a shared understanding of what a file should look like. They provide automatic write-time validation and generate review rules that enforce requirements during `/review` and workflow quality gates.
+
+### Two Flavors
+
+**Named schemas** (`.deepwork/schemas/<name>/deepschema.yml`) match files via glob patterns and are ideal for recurring file types — configs, API specs, job definitions, etc.
+
+**Anonymous schemas** (`.deepschema.<filename>.yml`) sit next to a specific file and apply only to that file.
+
+### What They Do
+
+1. **Write-time validation** — When an agent writes or edits a file, applicable schemas are checked immediately. JSON Schema validation and custom bash commands run automatically; failures are reported inline so the agent can fix them on the spot.
+2. **Review generation** — Each schema automatically produces a review rule. During `/review` or workflow quality gates, a reviewer checks every matched file against the schema's RFC 2119 requirements (MUST/SHOULD/MAY).
+3. **Inheritance** — Anonymous schemas can reference named schemas via `parent_deep_schemas` to inherit shared requirements.
+
+### Quick Example
+
+```yaml
+# .deepwork/schemas/api_endpoint/deepschema.yml
+summary: REST API endpoint handler
+matchers:
+  - "src/api/**/*.py"
+requirements:
+  auth-required: "Every endpoint MUST enforce authentication."
+  error-handling: "Endpoints MUST return structured error responses."
+  rate-limited: "Public endpoints SHOULD be rate-limited."
+json_schema_path: "openapi_fragment.schema.json"
+```
+
+Use `/deepschema` for the full reference on creating and managing schemas.
+
+---
+
 ## Supported Platforms
 
 | Platform | Status | Notes |
@@ -323,6 +357,7 @@ Send [@tylerwillis](https://x.com/tylerwillis) a message on X.
 your-project/
 ├── .deepwork/
 │   ├── tmp/               # Session state (created lazily)
+│   ├── schemas/           # DeepSchema definitions
 │   └── jobs/              # Job definitions
 │       └── job_name/
 │           └── job.yml    # Job definition (self-contained with inline instructions)

doc/architecture.md

@@ -61,11 +61,20 @@ deepwork/                       # DeepWork tool repository
 │       │       └── status.py       # Status file writer for external consumers
 │       ├── hooks/              # Hook system and cross-platform wrappers
 │       │   ├── wrapper.py      # Cross-platform input/output normalization
+│       │   ├── deepschema_write.py # DeepSchema write-time validation hook
 │       │   ├── claude_hook.sh  # Shell wrapper for Claude Code
 │       │   └── gemini_hook.sh  # Shell wrapper for Gemini CLI
+│       ├── deepschema/         # DeepSchema subsystem
+│       │   ├── config.py       # DeepSchema config parsing
+│       │   ├── discovery.py    # Find DeepSchema files in project tree
+│       │   ├── matcher.py      # Match files against DeepSchema rules
+│       │   ├── resolver.py     # Resolve DeepSchema definitions
+│       │   ├── review_bridge.py # Generate synthetic review rules from DeepSchemas
+│       │   └── schema.py       # DeepSchema data models
 │       ├── standard_jobs/      # Built-in job definitions
 │       │   ├── deepwork_jobs/
 │       │   └── deepwork_reviews/
+│       ├── standard_schemas/   # Built-in DeepSchema definitions
 │       ├── review/             # DeepWork Reviews system
 │       │   ├── config.py       # .deepreview config parsing + data models
 │       │   ├── discovery.py    # Find .deepreview files in project tree
@@ -76,6 +85,7 @@ deepwork/                       # DeepWork tool repository
 │       │   └── schema.py       # JSON schema loader
 │       ├── schemas/            # Definition schemas
 │       │   ├── deepreview_schema.json
+│       │   ├── deepschema_schema.json
 │       │   └── doc_spec_schema.py
 │       └── utils/
 │           ├── fs.py
@@ -94,8 +104,9 @@ deepwork/                       # DeepWork tool repository
 │   │   ├── skills/
 │   │   │   ├── deepwork/SKILL.md
 │   │   │   ├── review/SKILL.md
-│   │   │   └── configure_reviews/SKILL.md
-│   │   ├── hooks/              # hooks.json, post_commit_reminder.sh, post_compact.sh, startup_context.sh
+│   │   │   ├── configure_reviews/SKILL.md
+│   │   │   └── deepschema/SKILL.md
+│   │   ├── hooks/              # hooks.json, post_commit_reminder.sh, post_compact.sh, startup_context.sh, deepschema_write.sh
 │   │   └── .mcp.json           # MCP server config
 │   └── gemini/                 # Gemini CLI extension
 │       └── skills/deepwork/SKILL.md
@@ -141,6 +152,7 @@ deepwork review --instructions-for claude
 
 The review command:
 - Discovers `.deepreview` files throughout the project tree
+- Discovers DeepSchemas and generates synthetic review rules from them
 - Detects changed files via `git diff` against the default branch, plus untracked files via `git ls-files`
 - Matches changed files against rules using include/exclude glob patterns
 - Groups files by review strategy (`individual`, `matches_together`, `all_changed_files`)
@@ -807,7 +819,7 @@ All MCP server code lives in `src/deepwork/jobs/mcp/`.
 
 The FastMCP server definition that:
 - Creates and configures the MCP server instance
-- Registers the workflow tools and review tools (`get_review_instructions`, `get_configured_reviews`, `mark_review_as_passed`)
+- Registers the workflow tools, review tools (`get_review_instructions`, `get_configured_reviews`, `mark_review_as_passed`), and DeepSchema tools (`get_named_schemas`)
 - Detects job definition issues at startup via `issues.py` and appends warnings to tool responses
 - Provides server instructions for agents
 
@@ -903,6 +915,13 @@ Marks a review as passed so it is skipped on subsequent runs while the reviewed
 
 **Returns**: Confirmation string or validation error.
 
+#### 9. `get_named_schemas`
+Lists all named DeepSchemas discovered across all schema sources (project-local, standard, and env var). Returns each schema's name, summary, and matcher patterns.
+
+**Parameters**: None.
+
+**Returns**: List of `{name, summary, matchers}` dicts.
+
 ### Review Pass Caching
 
 Each review task is assigned a deterministic `review_id` encoding the rule name, file paths, and a SHA-256 content hash (first 12 hex chars). When `get_review_instructions` generates instruction files, it names them `{review_id}.md` and checks for a corresponding `{review_id}.passed` marker. If the marker exists, the review is skipped.

doc/initial_deepreview_spec.md

@@ -0,0 +1,55 @@
+# DeepSchema
+DeepWork Schemas (or DeepSchemas) are an enrichment of the DeepReview system wherein you can have a rich schema for files that are helpful for both humans and for agents.
+
+## Types of DeepSchemas
+1. `named` DeepSchemas are ones placed in `.deepwork/schemas/` or a similar schema registry. 
+2. `anonymous` DeepSchemas are ones that are declared in the normal file system alongside files they affect. These are specific to individual files, and have names of the format `.deepschema.<filename>.yml` where `filename` is the file they apply to.
+
+## Named DeepSchemas
+Named DeepSchemas are directories where the final segment of the path is the name of the schema. The files inside the directories are then as follows:
+* deepschema.yml - the manifest file
+* `examples` - a directory of example files
+* `references` - additional reference files relevant to the schema
+* `schema file with any name` - JSON Schema for the file or any other types of normal schemas go in the main directory. All optional
+
+### Named Schema Discovery Sources
+Named schemas are discovered from multiple directories in priority order. If the same schema name (directory name) appears in multiple sources, the first one wins.
+
+1. `<project_root>/.deepwork/schemas/` — project-local named schemas
+2. `<deepwork_package>/standard_schemas/` — built-in standard schemas shipped with DeepWork (analogous to `standard_jobs/`)
+3. `DEEPWORK_ADDITIONAL_SCHEMAS_FOLDERS` environment variable — colon-delimited list of absolute paths to additional directories containing named schema subdirectories
+
+This mirrors the job discovery system (`DEEPWORK_ADDITIONAL_JOBS_FOLDERS`).
+
+## Anonymous DeepSchemas
+These have only the single file. That file is the same format as the `deepschema.yml` file in the named DeepSchemas.
+
+## Files
+### deepschema.yml
+These yaml files have the following keys. They are all usable in both anonymous and named DeepSchemas, but we separate them below into the ones that are common in both and ones mostly relevant to Named ones.
+1. Common to Both
+	1. `requirements` - object where the keys are names and the bodies are descriptions of the requirements that a good document meets. These use RFC 2119 words that guide the reviews; MUST, SHOULD, etc. This is the same format / type as `process_requirements` in DeepWork Jobs
+	2. `parent_deep_schemas` - array of the names of other schemas that apply to anything this applies to.
+		1. Mostly used in anonymous DeepSchemas to reference in a named DeepSchema when needed
+	3. `json_schema_path` - relative path to a JSON schema file to enforce
+	4. `verification_bash_command` - arbitrary array of strings of bash commands to be run on the file to verify it. Main example use is if there is a different kind of schema other than a JSON one that you want to enforce
+2. `summary` Summary of the type. Used for giving a high-level understanding and for search / discovery
+3. `instructions` - general instructions for dealing with files of this type. 
+4. `examples` - array of examples of files of this type done well. Each entry should have a relative path from the definition file and a description.
+5. `references` - more detailed reference files that can be looked at on particular topics related to the file. These have relative paths and descriptions. Can also also have URLs in place of relative paths
+6. `matchers` - a declaration of file patterns that the schema applies to. This is an array of glob patterns
+
+## Behavior
+1. There must be a concept of "applicable schemas" for a given file. This should be computed using a reusable method. It should match any named schemas that have matchers that match up with a given file, or anonymous schemas named `.deepschema.<filename>.yml` for that file
+2. Whenever a file is written by an agent (PostToolUse on Write/Edit), a conformance note must be sent: "Note: this file must conform to the DeepSchema at <project relative path/>". Additionally, the `verification_bash_command` must be executed automatically. If it fails, then a message must be returned to the agent saying "CRITICAL: DeepSchema validation failed when it tried to verify this change. Error: <stdout + stderr from the failed command/>"
+	1. If there was a `json_schema_path`, then it must also generate a similar message if the file does not conform to the schema
+	2. No read hook is used — schema awareness is delivered via the write hook to avoid per-read latency
+4. DeepReview must be modified so that there are "reviews" generated for every type definition. 
+	1. These should have the relevant deepschema.yml used as the origin file.
+	2. They should all be single-file-at-a-time reviews
+	3. Their names should be "<named schema name | anonymous schemas target file name/> DeepSchema Compliance"
+	4. The instructions for the review should be (roughly): 
+		1. Named schemas intro: "<file path/> is an instance of <schema name/>, described as follows:\n<schema summary/>\n\nInstructions for dealing with these files:\n<instructions/>"
+		2. Anonymous schemas intro: "<file path/> has requirements that it must follow."
+		3. Body for both types: "Please review for compliance with the following requirements. You must fail reviews over anything that is MUST. You must fail reviews over any SHOULD that seems like it could be easily followed but is not. You should give feedback but not fail over anything else applicable. You can ignore N/A requirements.\n\n <requirements/>"
+	5. These reviews should run both from `/review` and from DeepWork jobs when steps finish like regular DeepReviews are run