feat(standard_jobs): add engineer standard job#287
Conversation
Domain-agnostic engineering execution job with two workflows: - implement: 6-step workflow (translate_issue -> initialize_branch -> red_tests -> green_implementation -> finalize_pr -> product_sync) - doctor: 3-step workflow validating agent.md and context files Enforces TDD discipline, PR synchronization, artifact generation, CODEOWNERS-based reviewer assignment, and product traceability per bundled RFC 2119 requirements specification. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Trim step instructions by 33% (1218→816 lines): remove redundant quality criteria sections, domain adaptation tables (already in common_job_info), and verbose objective/task preambles - Fix requirements.md: correct "REQUIRED" keyword usage, clarify CI agent responsibility, add audience statement and section headings - Update CLAUDE.md and doc/architecture.md to list engineer standard job - Add .deepreview config for holistic job definition review Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new built-in engineer standard job under src/deepwork/standard_jobs/engineer/ to support a domain-agnostic engineering workflow with an implement and doctor workflow, plus repository documentation updates referencing the new job.
Changes:
- Added the
engineerstandard job definition (job.yml), RFC-2119 requirements spec, and step instruction files forimplementanddoctorworkflows. - Added a job-scoped
.deepreviewrule to enable holistic review of the job definition and its steps. - Updated repository docs (
AGENTS.md,doc/architecture.md) to list and describe the new standard job.
Reviewed changes
Copilot reviewed 16 out of 16 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| src/deepwork/standard_jobs/engineer/job.yml | Defines the engineer job, workflows, steps, IO chain, and review criteria. |
| src/deepwork/standard_jobs/engineer/requirements.md | Adds normative RFC 2119 requirements referenced by the job/steps. |
| src/deepwork/standard_jobs/engineer/.deepreview | Adds a holistic review rule for the job definition and step instructions. |
| src/deepwork/standard_jobs/engineer/AGENTS.md | Documents job location, structure, workflows, and design decisions. |
| src/deepwork/standard_jobs/engineer/CLAUDE.md | Provides Claude-facing job context entry (symlink/alias behavior per repo conventions). |
| src/deepwork/standard_jobs/engineer/steps/translate_issue.md | Step instructions for translating product issues into engineering issues. |
| src/deepwork/standard_jobs/engineer/steps/initialize_branch.md | Step instructions for branching/spec commit + drafting PR. |
| src/deepwork/standard_jobs/engineer/steps/red_tests.md | Step instructions for producing/validating failing tests and manifest output. |
| src/deepwork/standard_jobs/engineer/steps/green_implementation.md | Step instructions for implementing to green + progress synchronization. |
| src/deepwork/standard_jobs/engineer/steps/finalize_pr.md | Step instructions for artifact verification, PR demo/handoff, and review readiness. |
| src/deepwork/standard_jobs/engineer/steps/product_sync.md | Step instructions for posting a closure/progress comment back to the product issue. |
| src/deepwork/standard_jobs/engineer/steps/check_agent_md.md | Step instructions for auditing presence/quality of agent context + CODEOWNERS. |
| src/deepwork/standard_jobs/engineer/steps/check_context.md | Step instructions for auditing referenced context files’ presence/syntax/link health. |
| src/deepwork/standard_jobs/engineer/steps/doctor_report.md | Step instructions for producing a readiness report from the audits. |
| doc/architecture.md | Adds engineer job description to the architecture documentation. |
| AGENTS.md | Adds engineer to the “Current standard jobs” section and updates the directory tree snippet. |
| The workflow is domain-agnostic. Each step's instructions include a domain adaptation | ||
| table mapping generic concepts to domain-specific equivalents: |
There was a problem hiding this comment.
The common job info says “Each step's instructions include a domain adaptation table…”, but none of the step instruction files include that table (the table only exists here in common_job_info). This is misleading for readers/agents—either add the table to each step file, or update this text to state that the domain adaptation table is provided via common_job_info.
| The workflow is domain-agnostic. Each step's instructions include a domain adaptation | |
| table mapping generic concepts to domain-specific equivalents: | |
| The workflow is domain-agnostic. This common job info provides a domain adaptation | |
| table mapping generic concepts to domain-specific equivalents that applies across all steps: |
|
|
||
| ## Design Decisions | ||
|
|
||
| 1. **Domain-agnostic**: Step instructions include domain adaptation tables (software, hardware, CAD, firmware, docs) |
There was a problem hiding this comment.
This design decision says step instructions include domain adaptation tables, but the step instruction files don’t actually include any domain adaptation table (it’s only present in job.yml common_job_info). Please update this statement or add the missing tables so the documentation matches reality.
| 1. **Domain-agnostic**: Step instructions include domain adaptation tables (software, hardware, CAD, firmware, docs) | |
| 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. |
| The #demo section of the PR MUST display the automatically generated visual | ||
| artifacts to facilitate asynchronous review. | ||
|
|
||
| If the implementation unblocks downstream work or requires specific | ||
| staging/production verification, the engineer MUST document this in a formal | ||
| comment or within the #handoff section of the PR. |
There was a problem hiding this comment.
The requirements refer to “#demo” and “#handoff” sections, but the step instructions/output templates use “## Demo” / “## Handoff”. To avoid ambiguity in a normative spec, please align the requirements wording with the actual section headings you expect in PRs (or explicitly define whether these are headings vs anchors).
| The #demo section of the PR MUST display the automatically generated visual | |
| artifacts to facilitate asynchronous review. | |
| If the implementation unblocks downstream work or requires specific | |
| staging/production verification, the engineer MUST document this in a formal | |
| comment or within the #handoff section of the PR. | |
| The `## Demo` section of the PR MUST display the automatically generated visual | |
| artifacts to facilitate asynchronous review. | |
| If the implementation unblocks downstream work or requires specific | |
| staging/production verification, the engineer MUST document this in a formal | |
| comment or within the `## Handoff` section of the PR. |
|
|
||
| **Current standard jobs**: | ||
| - `deepwork_jobs` - Core job management (define, implement, learn) | ||
| - `engineer` - Domain-agnostic engineering execution (implement, doctor) |
There was a problem hiding this comment.
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.
| - `engineer` - Domain-agnostic engineering execution (implement, doctor) | |
| - `engineer` - Domain-agnostic engineering execution (implement, doctor) | |
| - `deepwork_reviews` - DeepWork job review and quality control workflows |
| - id: finalize_pr | ||
| name: "Finalize PR with Artifacts" | ||
| description: "Ensure CI generates visual artifacts, populate the PR #demo section, document handoff notes, and verify all checkboxes are complete." | ||
| instructions_file: steps/finalize_pr.md | ||
| inputs: | ||
| - file: .deepwork/tmp/branch_context.md | ||
| from_step: initialize_branch | ||
| - file: .deepwork/tmp/implementation_summary.md | ||
| from_step: green_implementation | ||
| outputs: | ||
| .deepwork/tmp/pr_finalization.md: | ||
| type: file | ||
| description: "PR finalization status: artifact verification, demo section, handoff notes, checkbox state" | ||
| required: true | ||
| dependencies: | ||
| - initialize_branch | ||
| - green_implementation | ||
| reviews: | ||
| - run_each: .deepwork/tmp/pr_finalization.md | ||
| quality_criteria: | ||
| "Visual Artifacts Present": "The PR #demo section displays automatically generated visual artifacts relevant to the domain." |
There was a problem hiding this comment.
The finalize_pr step description/quality criteria refer to the PR “#demo section”, but the step instruction template/output format uses “## Demo” / “## Demo Section”. Please standardize this across job.yml, requirements.md, and steps/finalize_pr.md so the workflow has one unambiguous expected PR section name.
| - Each instruction file has clear sections: Objective, Task/Process, | ||
| Output Format, and Quality Criteria | ||
| - 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 |
There was a problem hiding this comment.
The review instructions require each step instruction file to have sections like Objective/Task/Output Format/Quality Criteria/Context, but the engineer step files currently only have a brief intro + “## Process” + “## Output Format” (no Objective/Task/Quality Criteria/Context sections). Either adjust these review instructions for this job’s intended style, or expand the step files to match the stated expectations so the holistic review rule doesn’t fail by construction.
| - Each instruction file has clear sections: Objective, Task/Process, | |
| Output Format, and Quality Criteria | |
| - 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 | |
| - 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. |
doc/architecture.md
Outdated
| - **`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 — step instructions include domain adaptation tables for software, hardware/CAD, firmware, and documentation projects. An RFC 2119 requirements specification is bundled as `requirements.md`. |
There was a problem hiding this comment.
This sentence claims the step instructions include domain adaptation tables, but the domain adaptation table is actually in the job’s common_job_info (and the step files don’t include tables). Suggest updating this description to reflect where the table really lives so the architecture docs stay accurate.
| The job is domain-agnostic — step instructions include domain adaptation tables for software, hardware/CAD, firmware, and documentation projects. An RFC 2119 requirements specification is bundled as `requirements.md`. | |
| 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`. |
| description: "Review job.yml and step instructions for correctness, completeness, and coherence as a holistic workflow." | ||
| match: | ||
| include: | ||
| - "job.yml" | ||
| - "steps/*.md" | ||
| review: | ||
| strategy: matches_together | ||
| instructions: | | ||
| Review this DeepWork job definition (job.yml) and its step instruction files | ||
| (steps/*.md) holistically. Check that they form a coherent, well-structured | ||
| workflow that an AI agent can execute reliably. |
There was a problem hiding this comment.
This holistic job-definition review rule matches only job.yml and steps/*.md, but this job also relies on requirements.md (and step instructions reference Req 1–8). Consider including requirements.md in the match set so reviewers evaluate the normative spec alongside the job/steps.
| description: "Review job.yml and step instructions for correctness, completeness, and coherence as a holistic workflow." | |
| match: | |
| include: | |
| - "job.yml" | |
| - "steps/*.md" | |
| review: | |
| strategy: matches_together | |
| instructions: | | |
| Review this DeepWork job definition (job.yml) and its step instruction files | |
| (steps/*.md) holistically. Check that they form a coherent, well-structured | |
| workflow that an AI agent can execute reliably. | |
| 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. |
| Ensure CI generates visual artifacts, populate the PR #demo section, document handoff | ||
| notes, verify all checkboxes are complete, and undraft the PR for review. | ||
|
|
||
| ## Process | ||
|
|
||
| 1. **Verify CI artifacts** — confirm the pipeline produced domain-appropriate visual artifacts | ||
| (DOM snapshots, rendered STLs, logic traces, PDF renders, etc.). If CI does not produce | ||
| artifacts, document the gap and manually capture equivalents. | ||
| 2. **Populate the ## Demo section** — add visual artifacts with captions and before/after | ||
| comparisons where applicable |
There was a problem hiding this comment.
This step mixes “PR #demo section” (line 3) with “## Demo section” (line 11) and later uses a “## Demo Section” heading in the output template. Please standardize the terminology/expected heading (and align with requirements.md) so agents know exactly what section to populate.
Align documentation with implementation: - Fix domain adaptation table references to say they live in common_job_info, not in step instructions (job.yml, AGENTS.md, doc/architecture.md) - Standardize PR section references to `## Demo` and `## Handoff` across requirements.md, job.yml, and finalize_pr.md - Add deepwork_reviews to standard jobs list in repo AGENTS.md - Include requirements.md in .deepreview match set - Update .deepreview step instruction quality criteria to match actual file structure Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Summary
engineerstandard job insrc/deepwork/standard_jobs/engineer/with two workflows:implement(6 steps):translate_issue→initialize_branch→red_tests→green_implementation→finalize_pr→product_syncdoctor(3 steps):check_agent_md→check_context→doctor_reportrequirements.md.deepreviewconfig for holistic job definition reviewDesign decisions
common_job_infocovers software, hardware/CAD, firmware, and docsproduct_syncis separate: workflow can pause atfinalize_prwhile PR undergoes human reviewrepolibrary job for labels/branch protection/milestonesTest plan
job.ymlvalidates againstjob.schema.jsonuv run pytest— 759 passed, 0 failedget_workflowsshowsengineerjob (requires merge — standard job discovery reads from installed package)implementworkflow on a real issue🤖 Generated with Claude Code