Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ When creating or modifying jobs in this repository, you MUST understand which ty

**Current standard jobs**:
- `deepwork_jobs` - Core job management (define, implement, learn)
- `engineer` - Domain-agnostic engineering execution (implement, doctor)
Copy link

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The “Current standard jobs” list is missing deepwork_reviews, but src/deepwork/standard_jobs/deepwork_reviews/ exists (and is documented elsewhere in the repo). Please add it here so the list stays complete.

Suggested change
- `engineer` - Domain-agnostic engineering execution (implement, doctor)
- `engineer` - Domain-agnostic engineering execution (implement, doctor)
- `deepwork_reviews` - DeepWork job review and quality control workflows

Copilot uses AI. Check for mistakes.
- `deepwork_reviews` - DeepWork job review and quality control workflows

**Editing rules**:
- Source of truth is ALWAYS in `src/deepwork/standard_jobs/`
Expand Down Expand Up @@ -104,7 +106,8 @@ deepwork/
│ ├── hooks/ # Hook scripts and wrappers
│ ├── standard_jobs/ # Built-in job definitions (auto-discovered at runtime)
│ │ ├── deepwork_jobs/
│ │ └── deepwork_reviews/
│ │ ├── deepwork_reviews/
│ │ └── engineer/
│ ├── review/ # DeepWork Reviews system (.deepreview pipeline)
│ ├── schemas/ # Definition schemas (deepreview, doc_spec)
│ └── utils/ # Utilities (fs, git, yaml, validation)
Expand Down Expand Up @@ -221,7 +224,7 @@ Each step:

### How to Identify Job Types

- **Standard jobs**: Exist in `src/deepwork/standard_jobs/` (currently: `deepwork_jobs`, `deepwork_reviews`)
- **Standard jobs**: Exist in `src/deepwork/standard_jobs/` (currently: `deepwork_jobs`, `deepwork_reviews`, `engineer`)
- **Library jobs**: Exist in `library/jobs/`
- **Bespoke jobs**: Exist ONLY in `.deepwork/jobs/` with no corresponding standard_jobs entry

Expand All @@ -242,3 +245,4 @@ Each step:
5. **Type Safety**: Use type hints for better code quality
6. **No Auto-Commit**: DO NOT automatically commit changes to git. Let the user review and commit changes themselves.
7. **Documentation Sync**: When making implementation changes, always update `doc/architecture.md` and `README.md` to reflect those changes. The architecture document must stay in sync with the actual codebase.
8. **Succinctness**: Jobs, documentation, and code MUST be succinct. Avoid verbose preambles, redundant explanations, and duplicated content. Step instructions should contain only what the agent needs to act — not philosophy, not quality criteria already enforced by the workflow runtime, and not domain tables already in `common_job_info`. If it can be said in one sentence, do not use three.
15 changes: 14 additions & 1 deletion doc/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,8 @@ deepwork/ # DeepWork tool repository
│ │ └── gemini_hook.sh # Shell wrapper for Gemini CLI
│ ├── standard_jobs/ # Built-in job definitions
│ │ ├── deepwork_jobs/
│ │ └── deepwork_reviews/
│ │ ├── deepwork_reviews/
│ │ └── engineer/
│ ├── review/ # DeepWork Reviews system
│ │ ├── config.py # .deepreview config parsing + data models
│ │ ├── discovery.py # Find .deepreview files in project tree
Expand Down Expand Up @@ -617,6 +618,18 @@ DeepWork includes a built-in job called `deepwork_reviews` for managing `.deepre
- **`add_document_update_rule`** workflow: `analyze_dependencies` → `apply_rule`
- Adds a review rule to keep a specific documentation file up-to-date when related source files change

### Standard Job: `engineer`

DeepWork includes a built-in job called `engineer` for domain-agnostic engineering execution. It provides:

**Workflows**:
- **`implement`** workflow: `translate_issue` → `initialize_branch` → `red_tests` → `green_implementation` → `finalize_pr` → `product_sync`
- Drives engineering work from product issue through PR merge with TDD discipline, PR synchronization, and product traceability
- **`doctor`** workflow: `check_agent_md` → `check_context` → `doctor_report`
- Validates that agent.md and domain context files are present, linked, and valid

The job is domain-agnostic — its `common_job_info` includes a domain adaptation table for software, hardware/CAD, firmware, and documentation projects that step instructions reference. An RFC 2119 requirements specification is bundled as `requirements.md`.

### MCP-Based Workflow Execution

Users invoke workflows through the `/deepwork` skill, which uses MCP tools:
Expand Down
81 changes: 81 additions & 0 deletions src/deepwork/standard_jobs/engineer/.deepreview
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
job_definition_review:
description: "Review job.yml, requirements.md, and step instructions for correctness, completeness, and coherence as a holistic workflow."
match:
include:
- "job.yml"
- "steps/*.md"
- "requirements.md"
review:
strategy: matches_together
instructions: |
Review this DeepWork job definition (job.yml), its requirements (requirements.md),
and its step instruction files (steps/*.md) holistically. Check that they form a
coherent, well-structured workflow that an AI agent can execute reliably.

## Reference Material

For reference on correct job structure and best practices, read the following files from your plugin:
- `job.yml.template` — canonical job.yml structure with all supported fields
- `job.yml.example` — a complete working example (competitive research job)
- `step_instruction.md.template` — expected structure for step instruction files
- `research_report_job_best_practices.md` — design patterns for report-type jobs

## What to Check

### 1. job.yml Structure
- Has required fields: `name`, `version`, `summary`, `workflows`, `steps`
- `name` is lowercase with underscores only
- `summary` is concise (under 200 characters) and descriptive enough to let a user know what the job does
- `version` follows semantic versioning (e.g., "1.0.0")
- `common_job_info_provided_to_all_steps_at_runtime` provides useful shared context (problem domain, terminology, conventions, constraints)

### 2. Workflow Coherence
- Each workflow's steps form a logical sequence toward a clear goal
- Step dependencies are declared correctly (no missing or extraneous deps)
- No circular dependencies exist

### 3. Input/Output Chain
- Each step has at least one output
- File inputs reference outputs from steps listed in that step's dependencies
- `from_step` values match actual step IDs that produce the referenced file
- The output chain creates a logical data flow through the workflow
- Intermediate outputs that are not meant to be persisted should be in .deepwork/tmp (and the name should indicate that)
- Final outputs follow project conventions (not hidden in dot-directories, descriptive names, appropriate use of subdirectories)

### 4. Step Instructions Match job.yml
- Every step defined in job.yml has a corresponding instruction file
- Step instruction content aligns with the step's described purpose
- Instructions reference the correct input and output filenames from job.yml
- Instructions do not duplicate content already in `common_job_info_provided_to_all_steps_at_runtime`
- If there is duplicated content amongst the instruction files, it should be moved to `common_job_info_provided_to_all_steps_at_runtime` and removed from the instruction files
- If there is content that is needed in multiple steps but not all, it should be moved to its own file and referenced in the steps

### 5. Quality Reviews
- Steps with complex or final outputs have reviews defined
- `run_each` values reference valid output names or `step`
- Quality criteria are statements of expected state, not questions
- `additional_review_guidance` is used when reviewers need context beyond the step's own output files (e.g., cross-referencing prior step outputs)
- Steps with no meaningful quality checks use `reviews: []`

### 6. Step Instruction Quality
- Each instruction file follows the structure and section headings defined in
`step_instruction.md.template` for this job type.
- The sections clearly communicate: what the step is trying to achieve,
what the agent should do, what to produce (including format/examples),
and how quality will be evaluated.
- Instructions are specific and actionable, not generic placeholders
- Output format sections show what good output looks like (examples or
templates)
- If the step gathers user input, instructions mention using structured
questions (e.g., the AskUserQuestion tool)
- Instructions explain how to use file inputs from prior steps and how the
step's outputs will be consumed by later steps.

## Output Format

- PASS: The job definition and step instructions are coherent and
well-structured.
- FAIL: List each issue with the specific file, the problem, and a
suggested fix.
additional_context:
unchanged_matching_files: true
43 changes: 43 additions & 0 deletions src/deepwork/standard_jobs/engineer/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Project Context for engineer

## Location

This job lives in the DeepWork package source at `src/deepwork/standard_jobs/engineer/`.
It is loaded directly at runtime by the multi-folder job discovery system.

## File Organization

```
engineer/
├── AGENTS.md # This file
├── CLAUDE.md -> AGENTS.md # Symlink for Claude Code
├── job.yml # Job definition
├── requirements.md # RFC 2119 requirements specification
└── steps/
├── translate_issue.md
├── initialize_branch.md
├── red_tests.md
├── green_implementation.md
├── finalize_pr.md
├── product_sync.md
├── check_agent_md.md
├── check_context.md
└── doctor_report.md
```

## Workflows

- **implement**: 6-step workflow executing engineering work from product issue through PR merge and product sync
- **doctor**: 3-step workflow validating agent.md and domain context files

## Design Decisions

1. **Domain-agnostic**: Domain adaptation tables (software, hardware, CAD, firmware, docs) live in `job.yml` `common_job_info`; step instructions are written to be domain-agnostic and rely on those tables
2. **Six implement steps**: Preserves TDD discipline boundary (red tests committed before green implementation)
3. **product_sync is separate**: Workflow can pause at finalize_pr while PR undergoes human review
4. **Doctor focuses on agent.md**: Recommends `repo` library job for labels/branch protection/milestones
5. **Requirements bundled**: RFC 2119 spec lives alongside job definition as `requirements.md`

## Last Updated
- Date: 2026-03-24
- From conversation about: Initial creation of the engineer standard job
1 change: 1 addition & 0 deletions src/deepwork/standard_jobs/engineer/CLAUDE.md
Loading
Loading