From fbea1e46c5d72aa3bd8214f09a6e331f7394edbf Mon Sep 17 00:00:00 2001 From: Nicholas Romero Date: Tue, 24 Mar 2026 15:44:42 -0500 Subject: [PATCH 1/3] feat(standard_jobs): add engineer standard job 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) --- src/deepwork/standard_jobs/engineer/AGENTS.md | 43 +++ src/deepwork/standard_jobs/engineer/CLAUDE.md | 1 + src/deepwork/standard_jobs/engineer/job.yml | 291 ++++++++++++++++++ .../standard_jobs/engineer/requirements.md | 94 ++++++ .../engineer/steps/check_agent_md.md | 102 ++++++ .../engineer/steps/check_context.md | 83 +++++ .../engineer/steps/doctor_report.md | 91 ++++++ .../engineer/steps/finalize_pr.md | 105 +++++++ .../engineer/steps/green_implementation.md | 94 ++++++ .../engineer/steps/initialize_branch.md | 78 +++++ .../engineer/steps/product_sync.md | 87 ++++++ .../standard_jobs/engineer/steps/red_tests.md | 86 ++++++ .../engineer/steps/translate_issue.md | 98 ++++++ 13 files changed, 1253 insertions(+) create mode 100644 src/deepwork/standard_jobs/engineer/AGENTS.md create mode 120000 src/deepwork/standard_jobs/engineer/CLAUDE.md create mode 100644 src/deepwork/standard_jobs/engineer/job.yml create mode 100644 src/deepwork/standard_jobs/engineer/requirements.md create mode 100644 src/deepwork/standard_jobs/engineer/steps/check_agent_md.md create mode 100644 src/deepwork/standard_jobs/engineer/steps/check_context.md create mode 100644 src/deepwork/standard_jobs/engineer/steps/doctor_report.md create mode 100644 src/deepwork/standard_jobs/engineer/steps/finalize_pr.md create mode 100644 src/deepwork/standard_jobs/engineer/steps/green_implementation.md create mode 100644 src/deepwork/standard_jobs/engineer/steps/initialize_branch.md create mode 100644 src/deepwork/standard_jobs/engineer/steps/product_sync.md create mode 100644 src/deepwork/standard_jobs/engineer/steps/red_tests.md create mode 100644 src/deepwork/standard_jobs/engineer/steps/translate_issue.md diff --git a/src/deepwork/standard_jobs/engineer/AGENTS.md b/src/deepwork/standard_jobs/engineer/AGENTS.md new file mode 100644 index 00000000..8451e712 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/AGENTS.md @@ -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**: Step instructions include domain adaptation tables (software, hardware, CAD, firmware, docs) +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 diff --git a/src/deepwork/standard_jobs/engineer/CLAUDE.md b/src/deepwork/standard_jobs/engineer/CLAUDE.md new file mode 120000 index 00000000..47dc3e3d --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/src/deepwork/standard_jobs/engineer/job.yml b/src/deepwork/standard_jobs/engineer/job.yml new file mode 100644 index 00000000..aff96740 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/job.yml @@ -0,0 +1,291 @@ +# yaml-language-server: $schema=.deepwork/schemas/job.schema.json +name: engineer +version: "1.0.0" +summary: "Domain-agnostic engineering execution from product issue through PR merge and product sync, with TDD discipline" +common_job_info_provided_to_all_steps_at_runtime: | + This job drives engineering work from product issue through merged PR and product sync. + It enforces test-driven development, continuous PR synchronization, artifact generation, + and product traceability across any engineering domain (software, hardware, CAD, firmware, + documentation). + + ## Requirements Reference + + This job implements an RFC 2119 requirements specification bundled as `requirements.md` + in the job directory. Step instructions reference requirements by number (Req 1-8). + Read `requirements.md` for the full normative text. + + ## Domain Adaptation + + The workflow is domain-agnostic. Each step's instructions include a domain adaptation + table mapping generic concepts to domain-specific equivalents: + + | Concept | Software | Hardware/CAD | Firmware | Docs | + |-----------------|-------------------|--------------------|-------------------|------------------| + | Test | Unit/integration | DRC/simulation | HIL/unit test | Link check/lint | + | Build artifact | Binary/container | STL/STEP/Gerber | .hex/.bin | PDF/HTML | + | CI visual | DOM snapshot | Rendered STL | Logic trace | PDF render | + | Branch | Git branch | Git branch | Git branch | Git branch | + + The agent MUST read the repository's `agent.md` (or equivalent context file) to determine + the project's domain and adapt accordingly. If no `agent.md` exists, the `doctor` workflow + SHOULD be run first. + + ## PR Synchronization + + Throughout the `implement` workflow, PR checkboxes MUST be kept synchronized with the + worktree state. Every time a task is completed and pushed, the corresponding PR checkbox + MUST be updated immediately. + + ## Work Product Storage + + Step outputs are DeepWork tracking files stored in `.deepwork/tmp/`. The actual engineering + artifacts (code, tests, configs, schematics) live in the repository's normal directory + structure as determined by the project's conventions. + +workflows: + - name: implement + summary: "Execute engineering work from product issue through PR merge and product sync" + steps: + - translate_issue + - initialize_branch + - red_tests + - green_implementation + - finalize_pr + - product_sync + + - name: doctor + summary: "Validate that agent.md and domain context files are present, linked, and valid" + steps: + - check_agent_md + - check_context + - doctor_report + +steps: + # ── Implement Workflow ───────────────────────────────────────────── + + - id: translate_issue + name: "Translate Product Issue to Engineering Issue" + description: "Read the product issue, extract requirements, and create a distinct engineering issue with implementation plan, test definitions, and traceability links." + instructions_file: steps/translate_issue.md + inputs: + - name: product_issue + description: "URL or identifier of the product issue containing the user story and requirements" + outputs: + .deepwork/tmp/engineering_issue.md: + type: file + description: "Engineering issue content: implementation plan, test definitions, and requirement traceability" + required: true + .deepwork/tmp/engineering_issue_url.md: + type: file + description: "URL of the created engineering issue on the git platform" + required: true + dependencies: [] + reviews: + - run_each: .deepwork/tmp/engineering_issue.md + quality_criteria: + "Implementation Plan Present": "The engineering issue contains a concrete implementation plan with actionable tasks." + "Test Definitions Present": "The engineering issue defines expected red and green test states for each requirement." + "Requirement Traceability": "Every requirement from the product issue is explicitly referenced and mapped to implementation tasks." + "Distinct From Product Issue": "The engineering issue is a separate artifact from the product issue, not a copy." + + - id: initialize_branch + name: "Initialize Branch and Draft PR" + description: "Create a dedicated git worktree or branch, commit the engineering specification, and open a draft PR using the repository's PR template." + instructions_file: steps/initialize_branch.md + inputs: + - file: .deepwork/tmp/engineering_issue.md + from_step: translate_issue + - file: .deepwork/tmp/engineering_issue_url.md + from_step: translate_issue + outputs: + .deepwork/tmp/branch_context.md: + type: file + description: "Branch name, PR URL, and initial commit SHA" + required: true + dependencies: + - translate_issue + reviews: + - run_each: .deepwork/tmp/branch_context.md + quality_criteria: + "Branch Created": "A dedicated branch or worktree exists for the engineering issue." + "Spec Committed": "The engineering specification was committed before any implementation code." + "Draft PR Opened": "A draft PR was opened using the repository's standardized PR template." + "PR Links Issue": "The PR references the engineering issue URL." + + - id: red_tests + name: "Write Failing Tests" + description: "Implement new failing tests or verify existing tests against new requirements. Each test must reference a specific requirement from the engineering issue." + instructions_file: steps/red_tests.md + inputs: + - file: .deepwork/tmp/engineering_issue.md + from_step: translate_issue + - file: .deepwork/tmp/branch_context.md + from_step: initialize_branch + outputs: + .deepwork/tmp/test_manifest.md: + type: file + description: "Manifest mapping each test to its requirement, with red state verification" + required: true + dependencies: + - translate_issue + - initialize_branch + reviews: + - run_each: .deepwork/tmp/test_manifest.md + additional_review_guidance: "Read .deepwork/tmp/engineering_issue.md to verify that every requirement has at least one corresponding test." + quality_criteria: + "Requirement Coverage": "Every requirement from the engineering issue has at least one corresponding test." + "Tests Are Red": "All new tests are verified to be in a failing state before implementation begins." + "Requirement References": "Each test explicitly references the specific requirement it validates." + "Tests Committed Separately": "Failing tests were committed separately from any implementation code." + + - id: green_implementation + name: "Implement to Pass Tests" + description: "Implement the necessary logic, parameters, or configuration to transition all tests to a passing state. Keep PR checkboxes synchronized with progress." + instructions_file: steps/green_implementation.md + inputs: + - file: .deepwork/tmp/engineering_issue.md + from_step: translate_issue + - file: .deepwork/tmp/branch_context.md + from_step: initialize_branch + - file: .deepwork/tmp/test_manifest.md + from_step: red_tests + outputs: + .deepwork/tmp/implementation_summary.md: + type: file + description: "Summary of implementation changes, test results, and PR checkbox state" + required: true + dependencies: + - translate_issue + - initialize_branch + - red_tests + reviews: + - run_each: .deepwork/tmp/implementation_summary.md + additional_review_guidance: "Read .deepwork/tmp/test_manifest.md to verify all tests transitioned from red to green." + quality_criteria: + "All Tests Green": "All tests from the test manifest have transitioned to a passing state." + "PR Checkboxes Synchronized": "PR checkboxes reflect the current state of completed tasks." + "Changes Pushed": "All implementation changes have been pushed to the remote branch." + "No Unrelated Changes": "The implementation contains only changes necessary to satisfy the requirements." + + - 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." + "Handoff Documented": "If the implementation unblocks downstream work, handoff notes are documented in the PR." + "Checkboxes Complete": "All PR task checkboxes are checked and synchronized with the branch state." + "PR Undrafted": "The PR has been undrafted (transitioned to ready for review) and code owner reviewers have been requested." + + - id: product_sync + name: "Synchronize Product Issue" + description: "After PR merge, author a formal comment on the parent product issue with completed user stories and immutable links to the merged PR and closed engineering issue." + instructions_file: steps/product_sync.md + inputs: + - file: .deepwork/tmp/engineering_issue_url.md + from_step: translate_issue + - file: .deepwork/tmp/branch_context.md + from_step: initialize_branch + - file: .deepwork/tmp/pr_finalization.md + from_step: finalize_pr + outputs: + .deepwork/tmp/product_sync_record.md: + type: file + description: "Record of the product issue comment: content posted, links included, timestamp" + required: true + dependencies: + - translate_issue + - initialize_branch + - finalize_pr + reviews: + - run_each: .deepwork/tmp/product_sync_record.md + quality_criteria: + "Comment Posted": "A formal comment was authored on the parent product issue." + "User Stories Documented": "The comment documents which high-level user stories were completed." + "Immutable Links": "The comment contains immutable links to the merged PR and closed engineering issue." + "Product Manager Visibility": "The comment provides enough context for product managers to understand progress without parsing engineering telemetry." + + # ── Doctor Workflow ──────────────────────────────────────────────── + + - id: check_agent_md + name: "Check Agent Context File" + description: "Verify that agent.md (or equivalent) exists, defines the engineering domain, and contains build/test/parse instructions for automated agents." + instructions_file: steps/check_agent_md.md + inputs: + - name: project_path + description: "Path to the repository root to check (defaults to current directory if omitted)" + outputs: + .deepwork/tmp/agent_md_audit.md: + type: file + description: "Audit results for agent.md: existence, domain declaration, build/test instructions" + required: true + dependencies: [] + reviews: + - run_each: .deepwork/tmp/agent_md_audit.md + quality_criteria: + "File Existence Checked": "The audit verifies whether agent.md (or equivalent) exists at the repository root." + "Domain Declared": "The audit checks whether the file explicitly defines the project's engineering domain." + "Agent Instructions Present": "The audit checks for build, test, and parse instructions that automated agents need." + "CODEOWNERS Present": "The audit checks for a CODEOWNERS file needed for automatic reviewer assignment." + + - id: check_context + name: "Check Supporting Context Files" + description: "Verify that supporting context files referenced by agent.md are present, correctly linked, and syntactically valid." + instructions_file: steps/check_context.md + inputs: + - file: .deepwork/tmp/agent_md_audit.md + from_step: check_agent_md + outputs: + .deepwork/tmp/context_audit.md: + type: file + description: "Audit results for supporting context files: broken links, missing files, syntax errors" + required: true + dependencies: + - check_agent_md + reviews: + - run_each: .deepwork/tmp/context_audit.md + additional_review_guidance: "Read .deepwork/tmp/agent_md_audit.md for context on which files were expected." + quality_criteria: + "References Resolved": "All file references from agent.md are checked for existence." + "Links Valid": "Symlinks and relative paths resolve correctly." + "Syntax Valid": "Referenced files are syntactically valid for their format (YAML, JSON, Markdown, etc.)." + + - id: doctor_report + name: "Doctor Report" + description: "Compile findings from agent.md and context audits into a pass/fail report with remediation instructions." + instructions_file: steps/doctor_report.md + inputs: + - file: .deepwork/tmp/agent_md_audit.md + from_step: check_agent_md + - file: .deepwork/tmp/context_audit.md + from_step: check_context + outputs: + .deepwork/tmp/doctor_report.md: + type: file + description: "Pass/fail report covering agent.md presence, domain declaration, context file integrity, and remediation steps" + required: true + dependencies: + - check_agent_md + - check_context + reviews: + - run_each: .deepwork/tmp/doctor_report.md + quality_criteria: + "All Checks Covered": "Report covers agent.md existence, domain declaration, agent instructions, and context file integrity." + "Pass/Fail Clear": "Each check has a clear pass or fail status." + "Remediation Provided": "Failed checks include specific remediation instructions." + "Repo Job Recommended": "If labels, branch protection, or milestones need attention, the report recommends the repo library job's doctor workflow." diff --git a/src/deepwork/standard_jobs/engineer/requirements.md b/src/deepwork/standard_jobs/engineer/requirements.md new file mode 100644 index 00000000..22febc19 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/requirements.md @@ -0,0 +1,94 @@ +# Engineer Job: RFC 2119 Requirements Specification + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in RFC 2119. + +Note: All general version control operations SHALL adhere to the current +established repository standards, beyond the explicit strictures defined below. + +## 1. Product and engineering issue delineation + +The workflow MUST initiate with a high-level Product Issue containing the +overarching user story and functional RFC 2119 requirements. + +An engineer MUST translate this Product Issue into a distinct Engineering Issue. + +The Engineering Issue REQUIRED payloads include the definitive implementation +plan, applicable schematics or CAD snippets, and explicit definitions of +expected red and green test states. + +## 2. Version control initialization + +A dedicated Git worktree or branch MUST be created specifically for the +Engineering Issue. + +The engineer SHALL commit the newly required specifications into the branch +prior to executing implementation code. + +A Pull Request (PR) MUST be opened in a draft state immediately following the +specification commit, strictly utilizing the repository's standardized PR +template. + +## 3. Test-driven execution and verification + +The engineer MUST either implement new failing (red) tests or explicitly verify +current existing tests against the new requirements. + +Each test MUST explicitly reference a specific requirement defined in the +Engineering Issue. + +The engineer SHALL implement the necessary logic, hardware parameters, or +configuration changes to transition the test suite to a passing (green) state. + +## 4. Continuous state synchronization + +The engineer MUST keep the PR checkboxes strictly synchronized with the state of +the active worktree. + +Checkboxes MUST be updated to reflect completion immediately as tasks are +finished and pushed to the remote branch. + +## 5. Artifact generation and continuous integration + +The automated Continuous Integration (CI) system MUST capture visual +representations of structural or interface alterations upon a successful green +state, and MUST include any of the following that are relevant to the domain: +rendered STLs, compiled schematics, localized DOM snapshots, or equivalent +visual artifacts. + +## 6. Pull request finalization and handoff + +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 PR SHALL NOT be merged until peer review validates the visual artifacts and +verifies that all synchronized task checkboxes are complete. + +## 7. Product synchronization + +Upon the successful merge of the PR and closure of the Engineering Issue, the +engineer MUST author a formal comment on the parent Product Issue. + +This comment MUST document the high-level user stories completed and provide +explicit, immutable links to the merged PR(s) and closed Engineering Issue(s), +ensuring product managers maintain up-to-date visibility without parsing +engineering telemetry. + +## 8. Contextual awareness and the doctor workflow + +To maintain a project-agnostic shared workflow, every repository MUST contain an +agent.md file (or equivalent domain documentation). + +This documentation MUST explicitly define the project's engineering domain (e.g., +AnchorCAD, web application, PCB layout) and instruct the automated agents on how +to parse, build, and test the repository. + +A separate doctor workflow MUST exist and be executed to validate that the +agent.md and related context files are present, correctly linked, and +syntactically valid, ensuring the automation agent knows how to interact with the +repository's specific medium. diff --git a/src/deepwork/standard_jobs/engineer/steps/check_agent_md.md b/src/deepwork/standard_jobs/engineer/steps/check_agent_md.md new file mode 100644 index 00000000..9a0f1593 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/check_agent_md.md @@ -0,0 +1,102 @@ +# Check Agent Context File + +## Objective + +Verify that agent.md (or equivalent domain documentation) exists at the repository root, +declares the engineering domain, and provides build/test/parse instructions for automated agents. + +## Task + +Audit the repository for the presence and completeness of its agent context file. This is the +foundational check — without a valid agent.md, the `implement` workflow cannot adapt to the +project's domain. + +### Process + +1. **Locate the agent context file** + - Check for common names at the repository root: + - `agent.md`, `AGENT.md` + - `AGENTS.md` + - `CLAUDE.md` (if it contains agent-relevant content, not just a symlink) + - `.claude/CLAUDE.md` (Claude Code project instructions) + - Check if any of these are symlinks and resolve them + - Record which file(s) were found and their paths + +2. **Check domain declaration** + - The file MUST explicitly define the project's engineering domain + - Valid domains include but are not limited to: web application, API service, mobile app, + CAD/mechanical, PCB/electronics, firmware/embedded, documentation site, data pipeline, + infrastructure/IaC, monorepo (with sub-domains) + - Record whether the domain is declared and what it is + +3. **Check agent instructions** + - The file MUST contain instructions for automated agents on how to: + - **Parse**: How to read/navigate the codebase (project structure, key files) + - **Build**: How to build or compile the project + - **Test**: How to run the test suite + - Record which instruction categories are present and which are missing + +4. **Check for CODEOWNERS** + - Check for a CODEOWNERS file in standard locations: + - `CODEOWNERS`, `.github/CODEOWNERS`, `docs/CODEOWNERS` (GitHub) + - Forgejo/Gitea equivalents if applicable + - If present, verify it contains at least one rule + - CODEOWNERS is REQUIRED for automatic reviewer assignment when PRs are undrafted + (Req 6) — its absence is a failure + +5. **Check for common issues** + - Empty or stub file (exists but has no real content) + - Circular symlinks + - References to files that don't exist + - Outdated information (e.g., references to deleted directories) + +## Output Format + +### .deepwork/tmp/agent_md_audit.md + +**Structure**: +```markdown +# Agent Context File Audit + +## File Discovery +- File found: yes/no +- Path: [path or "not found"] +- Is symlink: yes/no → [target] +- Format: [markdown/yaml/other] + +## Domain Declaration +- Domain declared: yes/no +- Domain: [declared domain or "not declared"] +- Specificity: [specific/vague/missing] + +## Agent Instructions +| Category | Present | Details | +|----------|---------|---------| +| Parse/Navigate | yes/no | [brief description or "missing"] | +| Build | yes/no | [brief description or "missing"] | +| Test | yes/no | [brief description or "missing"] | + +## CODEOWNERS +- File found: yes/no +- Path: [path or "not found"] +- Rules defined: [N rules or "empty"] + +## Issues Found +- [Issue 1: description] +- [Issue 2: description] +- [none] + +## Overall Status: [PASS/FAIL] +- Failures: [list of failed checks or "none"] + +## Referenced Files +[List of files referenced by agent.md that will be checked in the next step] +``` + +## Quality Criteria + +- All common agent file locations are checked +- Symlinks are resolved and validated +- Domain declaration is checked for specificity (not just presence) +- Build, test, and parse instructions are each independently verified +- Issues are specific and actionable diff --git a/src/deepwork/standard_jobs/engineer/steps/check_context.md b/src/deepwork/standard_jobs/engineer/steps/check_context.md new file mode 100644 index 00000000..40eb6419 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/check_context.md @@ -0,0 +1,83 @@ +# Check Supporting Context Files + +## Objective + +Verify that supporting context files referenced by agent.md are present, correctly linked, +and syntactically valid. + +## Task + +Follow every reference from the agent context file and verify the referenced files exist +and are well-formed. This catches broken links, missing files, and syntax errors that would +cause the `implement` workflow to fail or produce incorrect results. + +### Process + +1. **Extract references from agent.md audit** + - Read the `agent_md_audit.md` from the previous step + - Collect the list of referenced files identified there + - If agent.md was not found, report that no context files can be checked and note + that agent.md must be created first + +2. **Check each referenced file** + - For each file reference: + - Verify the file exists at the referenced path + - If it's a symlink, verify the target exists + - If it's a relative path, resolve it relative to agent.md's location + - Check that the file is not empty (zero bytes) + +3. **Validate syntax** + - For each file that exists, validate based on its extension: + - `.yml` / `.yaml`: Valid YAML (parseable without errors) + - `.json`: Valid JSON + - `.md`: Valid Markdown (no broken internal links within the file) + - `.toml`: Valid TOML + - `.nix`: Basic syntax check (balanced braces/brackets) + - For files with no recognized extension, skip syntax validation + +4. **Check for orphaned context files** + - Look for common context file patterns near agent.md that are NOT referenced: + - `CONTRIBUTING.md`, `ARCHITECTURE.md`, `DEVELOPMENT.md` + - `.editorconfig`, `.tool-versions`, `flake.nix` + - These are informational — report them as "available but unreferenced" (not failures) + +## Output Format + +### .deepwork/tmp/context_audit.md + +**Structure**: +```markdown +# Context File Audit + +## Source +- Agent context file: [path from audit] +- Agent context status: [PASS/FAIL from previous step] + +## Referenced Files + +| # | Path | Exists | Symlink | Syntax | Status | +|---|------|--------|---------|--------|--------| +| 1 | [path] | yes/no | yes→[target]/no | valid/invalid/skipped | PASS/FAIL | +| 2 | [path] | yes/no | no | valid | PASS | + +## Issues Found +- [Issue 1: description and remediation] +- [none] + +## Unreferenced Context Files +- [path] — [brief description of what it contains] +- [none found] + +## Overall Status: [PASS/FAIL] +- Referenced files checked: [N] +- Passed: [N] +- Failed: [N] +``` + +## Quality Criteria + +- Every file reference from agent.md is checked +- Symlinks are fully resolved +- Syntax validation matches the file format +- Broken references include specific paths for remediation +- Unreferenced context files are noted as informational, not failures diff --git a/src/deepwork/standard_jobs/engineer/steps/doctor_report.md b/src/deepwork/standard_jobs/engineer/steps/doctor_report.md new file mode 100644 index 00000000..41d3b211 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/doctor_report.md @@ -0,0 +1,91 @@ +# Doctor Report + +## Objective + +Compile findings from the agent.md and context file audits into a consolidated pass/fail +report with specific remediation instructions for any failures. + +## Task + +Synthesize the previous audit steps into a single actionable report. The report serves two +audiences: the human developer who needs to fix issues, and the `implement` workflow which +needs to know if the repository is ready for automated engineering execution. + +### Process + +1. **Read both audit files** + - Read `agent_md_audit.md` for agent context file findings + - Read `context_audit.md` for supporting file findings + - Collect all PASS and FAIL statuses + +2. **Compile the consolidated report** + - Organize findings by check category + - For each failed check, provide: + - What is wrong + - Why it matters (which workflow step would fail or produce bad results) + - Specific remediation steps (commands to run, content to add, files to create) + - For passing checks, confirm with a brief status line + +3. **Add cross-cutting recommendations** + - If labels, branch protection, or milestones need attention, recommend the `repo` + library job's `doctor` workflow — do not duplicate that job's scope + - If the repository lacks CI configuration, note this as it affects artifact generation + (Req 5) + - If the repository is a monorepo, note that each sub-project may need its own context + +4. **Determine overall readiness** + - READY: All checks pass — the `implement` workflow can proceed + - NOT READY: One or more critical checks fail — remediation is needed first + - PARTIAL: Non-critical issues exist but `implement` can proceed with caveats + +## Output Format + +### .deepwork/tmp/doctor_report.md + +**Structure**: +```markdown +# Engineer Doctor Report + +## Overall Status: [READY/NOT READY/PARTIAL] + +## Check Summary + +| # | Check | Status | Details | +|---|-------|--------|---------| +| 1 | Agent context file exists | PASS/FAIL | [brief detail] | +| 2 | Engineering domain declared | PASS/FAIL | [brief detail] | +| 3 | Build instructions present | PASS/FAIL | [brief detail] | +| 4 | Test instructions present | PASS/FAIL | [brief detail] | +| 5 | Parse/navigate instructions present | PASS/FAIL | [brief detail] | +| 6 | Referenced files exist | PASS/FAIL | [N/N passed] | +| 7 | Referenced files valid syntax | PASS/FAIL | [N/N passed] | +| 8 | CODEOWNERS file present | PASS/FAIL | [path or "not found"] | + +## Remediation Required + +### [Check Name] — FAIL +**Problem**: [what is wrong] +**Impact**: [which workflow step would fail] +**Fix**: +1. [specific step] +2. [specific step] + +### [Another Check] — FAIL +... + +## Recommendations +- [recommendation about repo job, CI, or other improvements] + +## Next Steps +- [If READY]: Run `engineer/implement` workflow to begin engineering work +- [If NOT READY]: Fix the issues listed above, then re-run `engineer/doctor` +- [If PARTIAL]: [specific caveats for proceeding] +``` + +## Quality Criteria + +- Every check from both audit steps is represented in the summary table +- Failed checks have specific, actionable remediation instructions +- The report distinguishes between critical failures and non-critical recommendations +- Cross-cutting recommendations reference existing jobs (e.g., `repo/doctor`) rather than duplicating scope +- The overall status accurately reflects whether the `implement` workflow can proceed diff --git a/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md b/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md new file mode 100644 index 00000000..634ac75e --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md @@ -0,0 +1,105 @@ +# Finalize PR with Artifacts + +## Objective + +Ensure CI generates visual artifacts, populate the PR #demo section with those artifacts, +document handoff notes, and verify all checkboxes are complete before requesting review. + +## Task + +Prepare the PR for peer review by ensuring all automated artifacts are captured, the demo +section showcases the changes, and any downstream implications are documented. + +### Process + +1. **Verify CI artifact generation** + - Confirm the CI pipeline ran successfully on the latest push + - Check that visual artifacts were generated (domain-appropriate): + - Software: DOM snapshots, screenshot diffs, API response samples + - Hardware/CAD: rendered STLs, compiled schematics, Gerber previews + - Firmware: logic analyzer traces, memory maps + - Docs: PDF renders, HTML previews + - If CI does not generate artifacts, document this as a gap and manually capture equivalents + +2. **Populate the #demo section** + - Add the automatically generated visual artifacts to the PR's `## Demo` section + - Include before/after comparisons where applicable + - Add brief captions explaining what each artifact shows + +3. **Document handoff notes** + - If the implementation unblocks downstream work, document in a `## Handoff` section: + - What is unblocked and for whom + - Any staging/production verification needed + - Migration steps if applicable + - If no downstream implications exist, note this explicitly + +4. **Final checkbox verification** + - Verify every PR task checkbox is checked + - Cross-reference against the engineering issue's implementation plan + - Ensure the branch is up to date with the base branch + +5. **Undraft and request review** + - MUST transition the PR from draft to ready-for-review state + - GitHub: `gh pr ready [PR-URL]` + - Forgejo/Gitea: equivalent API call to remove WIP/draft status + - Code owners (defined in `CODEOWNERS` or equivalent) are automatically requested as + reviewers when the PR is undrafted — verify this happened + - If the platform does not support automatic code owner assignment, manually request + the appropriate reviewers + - Note: the PR SHALL NOT be merged until peer review validates artifacts and checkboxes + +### Domain Adaptation + +| Concept | Software | Hardware/CAD | Firmware | Docs | +|------------------|-----------------------|------------------------|-----------------------|----------------------| +| CI artifacts | DOM snapshots, tests | STL renders, DRC | HIL logs, .hex size | PDF render, link check | +| Demo section | Screenshots, GIFs | 3D model views | Logic traces | Before/after content | +| Handoff | Deploy instructions | BOM update notes | Flash instructions | Publish instructions | + +## Output Format + +### .deepwork/tmp/pr_finalization.md + +**Structure**: +```markdown +# PR Finalization + +## CI Status +- Pipeline: [pass/fail/pending] +- Artifact generation: [available/not available/manual] + +## Visual Artifacts +| Artifact | Type | Location | +|----------|------|----------| +| [artifact name] | [STL render/screenshot/trace/etc.] | [URL or path] | + +## Demo Section +- Updated: yes/no +- Artifacts included: [N] +- Before/after comparisons: yes/no/not applicable + +## Handoff +- Downstream implications: [yes/no] +- Details: [description or "none"] +- Staging verification needed: [yes/no] + +## Checkbox State +- Total checkboxes: [N] +- Checked: [N] +- All synchronized: yes/no + +## Review Readiness +- PR undrafted: yes/no +- Code owner reviewers requested: [names or "not configured"] +- Additional reviewers: [names or "none"] +- Base branch up to date: yes/no +``` + +## Quality Criteria + +- CI artifacts are verified or manually captured +- The PR #demo section displays visual artifacts relevant to the domain +- Handoff notes document downstream implications (or explicitly state there are none) +- All PR checkboxes are checked and synchronized +- The PR is undrafted (transitioned to ready for review) +- Code owner reviewers are requested (or noted as not configured) diff --git a/src/deepwork/standard_jobs/engineer/steps/green_implementation.md b/src/deepwork/standard_jobs/engineer/steps/green_implementation.md new file mode 100644 index 00000000..85217663 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/green_implementation.md @@ -0,0 +1,94 @@ +# Implement to Pass Tests + +## Objective + +Implement the necessary logic, hardware parameters, or configuration changes to transition +all tests from red to green. Keep PR checkboxes synchronized with progress throughout. + +## Task + +Execute the implementation plan from the engineering issue, working test by test until the +entire suite passes. Maintain continuous state synchronization between the worktree and the +PR throughout. + +### Process + +1. **Review the implementation plan and test manifest** + - Read the engineering issue's implementation plan + - Read the test manifest to understand what each test expects + - Plan the implementation order (dependencies between tasks may dictate sequence) + +2. **Implement task by task** + - For each implementation task: + - Write the necessary code, configuration, or design changes + - Run the relevant tests to verify they transition from red to green + - Commit with a conventional commit message: `feat(scope): implement [task description]` + - Push to the remote branch + - **Immediately update the PR checkbox** for the completed task + +3. **Verify all tests green** + - Run the full test suite after all tasks are implemented + - Capture the test output showing all tests passing + - If any tests remain red, investigate and fix before proceeding + +4. **Synchronize PR state** + - Verify all PR checkboxes reflect the current branch state + - Update the PR description if the implementation diverged from the original plan + - Add a comment summarizing the implementation if noteworthy decisions were made + +### Domain Adaptation + +| Concept | Software | Hardware/CAD | Firmware | Docs | +|------------------|-----------------------|------------------------|-----------------------|----------------------| +| Implementation | Code changes | Schematic/model edits | Register/driver code | Content writing | +| Green state | Tests pass | DRC clean | Tests pass | Links valid, lint clean | +| Commit granularity | Per logical change | Per design change | Per module | Per section | + +## Output Format + +### .deepwork/tmp/implementation_summary.md + +**Structure**: +```markdown +# Implementation Summary + +## Overview +- Total tasks: [N] +- Tasks completed: [N] +- All tests green: yes/no + +## Implementation Details + +### Task 1: [task name] +- Requirement: Req [N] +- Changes: [files modified/created] +- Test result: PASS +- Commit: [sha] +- PR checkbox: updated + +### Task 2: [task name] +... + +## Test Suite Output +``` +[paste of test runner output showing all tests passing] +``` + +## PR State +- All checkboxes synchronized: yes/no +- Checkboxes checked: [N]/[total] +- Implementation divergences: [none, or description of changes from original plan] + +## Commits (in order) +1. [sha] — [commit message] +2. [sha] — [commit message] +... +``` + +## Quality Criteria + +- All tests from the test manifest have transitioned to green +- PR checkboxes are immediately updated as each task completes +- Each implementation change is committed and pushed individually +- No unrelated changes are included in the implementation +- The implementation follows the project's conventions from agent.md diff --git a/src/deepwork/standard_jobs/engineer/steps/initialize_branch.md b/src/deepwork/standard_jobs/engineer/steps/initialize_branch.md new file mode 100644 index 00000000..abc32aab --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/initialize_branch.md @@ -0,0 +1,78 @@ +# Initialize Branch and Draft PR + +## Objective + +Create a dedicated git worktree or branch for the engineering issue, commit the specification, +and open a draft PR using the repository's standardized PR template. + +## Task + +Set up the version control foundation for engineering work. The specification must be committed +before any implementation code, and a draft PR must exist immediately to enable continuous +synchronization. + +### Process + +1. **Create a dedicated branch or worktree** + - Branch naming: follow the repository's conventions (e.g., `feat/issue-123-description`) + - If the repository uses worktrees, create one; otherwise create a branch + - Ensure the branch is based on the latest default branch + +2. **Commit the engineering specification** + - Add the engineering issue content to the branch (e.g., as a spec file, or as the commit message) + - This commit MUST happen before any implementation code + - Use a conventional commit message: `docs(engineer): add engineering spec for #[issue-number]` + +3. **Open a draft PR** + - Use the repository's standardized PR template + - Title: follow repository conventions (e.g., `feat(scope): description`) + - Link the PR to the engineering issue + - Populate the task checklist from the engineering issue's implementation plan + - Mark the PR as draft + +4. **Record the branch context** + - Document the branch name, PR URL, and initial commit SHA + - This context is consumed by subsequent steps + +### Domain Adaptation + +| Concept | Software | Hardware/CAD | Firmware | Docs | +|------------------|---------------------|----------------------|---------------------|---------------------| +| Spec commit | API contract/schema | Design doc/BOM | Register map | Content outline | +| PR template | Code PR template | Design review form | HW/FW PR template | Doc review template | + +## Output Format + +### .deepwork/tmp/branch_context.md + +**Structure**: +```markdown +# Branch Context + +## Version Control +- Branch: [branch-name] +- Base: [default-branch] +- Initial Commit: [sha] + +## Pull Request +- URL: [pr-url] +- State: draft +- Template: [template used] + +## Engineering Issue +- URL: [engineering-issue-url] +- Linked in PR: yes/no + +## Task Checklist (from PR) +- [ ] Task 1: [description] +- [ ] Task 2: [description] +... +``` + +## Quality Criteria + +- Branch is based on the latest default branch +- Engineering spec was committed before any implementation code +- Draft PR uses the repository's standardized template +- PR is linked to the engineering issue +- Task checklist is populated from the implementation plan diff --git a/src/deepwork/standard_jobs/engineer/steps/product_sync.md b/src/deepwork/standard_jobs/engineer/steps/product_sync.md new file mode 100644 index 00000000..b97eb5d0 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/product_sync.md @@ -0,0 +1,87 @@ +# Synchronize Product Issue + +## Objective + +After PR merge and engineering issue closure, author a formal comment on the parent +product issue documenting completed user stories with immutable links to the merged PR +and closed engineering issue. + +## Task + +Close the traceability loop by updating the product issue so product managers have +up-to-date visibility without parsing engineering telemetry. This step is designed to +run after the PR has been merged — if the PR is still under review, pause and resume +this step later. + +### Process + +1. **Verify prerequisites** + - Confirm the PR has been merged (check PR state) + - Confirm the engineering issue is closed (check issue state) + - If either is still open, inform the user and pause — this step can be resumed later + via `go_to_step` + +2. **Gather immutable links** + - Merged PR URL (the canonical merged-state URL, not a draft URL) + - Closed engineering issue URL + - Any relevant commit SHAs for key changes + +3. **Identify completed user stories** + - Cross-reference the engineering issue's implementation plan with the product issue's + user story and requirements + - Summarize which high-level user stories were addressed + - Note any requirements that were partially addressed or deferred + +4. **Author the product issue comment** + - Post a formal comment on the parent product issue + - The comment MUST include: + - Which user stories were completed + - Immutable links to the merged PR and closed engineering issue + - Any deferred items or follow-up needed + - The comment SHOULD be written for a product manager audience (no engineering jargon) + +5. **Record the synchronization** + - Document what was posted and when + +### Domain Adaptation + +| Concept | Software | Hardware/CAD | Firmware | Docs | +|------------------|-----------------------|------------------------|-----------------------|----------------------| +| "Merged PR" | Code PR merged | Design PR merged | FW PR merged | Content PR merged | +| User story | Feature/fix | Design requirement | HW interface need | Content requirement | +| Follow-up | Tech debt, next phase | Prototype feedback | Integration test plan | Review feedback | + +## Output Format + +### .deepwork/tmp/product_sync_record.md + +**Structure**: +```markdown +# Product Sync Record + +## Prerequisites +- PR merged: yes/no — [PR URL] +- Engineering issue closed: yes/no — [issue URL] + +## Comment Posted +- Product issue: [product issue URL] +- Timestamp: [ISO 8601] + +## Comment Content +--- +[The exact text of the comment that was posted] +--- + +## Traceability +- User stories completed: [list] +- Deferred items: [list or "none"] +- Follow-up needed: [yes/no — description] +``` + +## Quality Criteria + +- The product issue comment was posted only after the PR was merged and engineering issue closed +- The comment includes immutable links to the merged PR and closed engineering issue +- User stories completed are summarized in product-manager-friendly language +- Any deferred items are explicitly documented +- The comment provides enough context for product visibility without engineering telemetry diff --git a/src/deepwork/standard_jobs/engineer/steps/red_tests.md b/src/deepwork/standard_jobs/engineer/steps/red_tests.md new file mode 100644 index 00000000..0db8cdd0 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/red_tests.md @@ -0,0 +1,86 @@ +# Write Failing Tests + +## Objective + +Implement new failing (red) tests or verify existing tests against the new requirements. +Each test must explicitly reference a specific requirement from the engineering issue. + +## Task + +Establish the test-driven development boundary. All tests must exist and fail before any +implementation code is written. This ensures requirements drive the implementation, not +the other way around. + +### Process + +1. **Review the engineering issue's test definitions** + - Read the test definitions table from `engineering_issue.md` + - Identify which tests need to be created vs. which existing tests can be reused + - Confirm the test framework and conventions from agent.md + +2. **Implement or verify tests** + - For each requirement, either: + - Write a new failing test that validates the requirement + - Verify an existing test covers the requirement and would fail without the new implementation + - Each test MUST include a comment or annotation referencing the specific requirement + (e.g., `# Req 3: Each test must reference a specific requirement`) + +3. **Verify red state** + - Run the test suite and confirm all new/modified tests fail + - Capture the test output showing the failures + - If any test unexpectedly passes, investigate — it may indicate the requirement is already met + +4. **Commit the failing tests** + - Commit tests separately from implementation: `test(scope): add failing tests for #[issue-number]` + - Push to the remote branch + - Update PR checkboxes for test-related tasks + +5. **Create the test manifest** + - Document each test, its requirement reference, and its red state verification + +### Domain Adaptation + +| Concept | Software | Hardware/CAD | Firmware | Docs | +|------------------|-----------------------|------------------------|-----------------------|----------------------| +| Test file | `test_*.py`, `*.test.ts` | DRC rule file | `test_*.c`, HIL script | `linkcheck.py`, lint config | +| Test runner | pytest, jest, cargo | KiCad DRC, FreeCAD | ceedling, Unity | sphinx linkcheck, markdownlint | +| Req reference | Docstring/comment | Rule comment | Test name/comment | Config comment | +| Red state | Test fails | DRC violation | Assert fails | Link broken/lint error | + +## Output Format + +### .deepwork/tmp/test_manifest.md + +**Structure**: +```markdown +# Test Manifest + +## Test Suite Summary +- Framework: [test framework] +- Total new tests: [N] +- Total verified existing tests: [N] +- Red state confirmed: yes/no + +## Test Details + +| # | Test | File | Requirement | Type | Red State | +|---|------|------|-------------|------|-----------| +| 1 | [test name] | [file:line] | Req [N] | new | FAIL: [failure reason] | +| 2 | [test name] | [file:line] | Req [N] | existing | FAIL: [failure reason] | + +## Test Output +``` +[paste of test runner output showing failures] +``` + +## Commits +- Test commit: [sha] — [commit message] +``` + +## Quality Criteria + +- Every requirement from the engineering issue has at least one test +- All new tests fail (red state) before implementation begins +- Each test references its requirement explicitly in code +- Tests were committed as a separate commit from implementation +- Test manifest accurately reflects the current state diff --git a/src/deepwork/standard_jobs/engineer/steps/translate_issue.md b/src/deepwork/standard_jobs/engineer/steps/translate_issue.md new file mode 100644 index 00000000..dc9d8901 --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/steps/translate_issue.md @@ -0,0 +1,98 @@ +# Translate Product Issue to Engineering Issue + +## Objective + +Read the product issue, extract its requirements, and create a distinct engineering issue +containing the implementation plan, test definitions, and traceability links. + +## Task + +Transform a high-level product issue (user story + requirements) into a concrete engineering +issue that an agent or engineer can execute against. The engineering issue is a separate +artifact — not a copy of the product issue. + +### Process + +1. **Read the product issue** + - Fetch the product issue using its URL or identifier + - Extract the user story and all functional requirements + - Identify any acceptance criteria, constraints, or non-functional requirements + - Note the product issue's labels, milestone, and assignees + +2. **Read the repository's agent.md** + - Determine the project's engineering domain from agent.md (or equivalent) + - Understand the build, test, and deployment conventions + - If agent.md does not exist, warn the user and recommend running the `doctor` workflow first + +3. **Draft the engineering issue** + - Write a definitive implementation plan with actionable tasks + - Define expected red and green test states for each requirement + - Include applicable schematics, CAD snippets, code references, or configuration details + - Map every product requirement to at least one implementation task + +4. **Create the engineering issue on the platform** + - Create a new issue on the git platform (GitHub, Forgejo, etc.) + - Label it with `engineering` + - Link it to the parent product issue + - Assign it to the same milestone if applicable + +### Domain Adaptation + +| Concept | Software | Hardware/CAD | Firmware | Docs | +|----------------------|---------------------|----------------------|---------------------|---------------------| +| Implementation plan | Code changes | Design changes | Register/driver map | Content outline | +| Test definitions | Unit/integration | DRC/simulation | HIL/unit test | Link check/lint | +| Schematics/snippets | API contracts | KiCad/FreeCAD refs | Pinout diagrams | IA diagrams | + +## Output Format + +### .deepwork/tmp/engineering_issue.md + +The engineering issue content, structured for both platform posting and step consumption. + +**Structure**: +```markdown +# Engineering Issue: [Title] + +## Parent Product Issue +- URL: [product_issue_url] +- User Story: [one-line summary] + +## Implementation Plan + +### Task 1: [task name] +- Requirement: Req [N] — [requirement summary] +- Description: [what to implement] +- Files: [expected files to create/modify] + +### Task 2: [task name] +... + +## Test Definitions + +| Test | Requirement | Red State (before) | Green State (after) | +|------|-------------|---------------------|---------------------| +| [test name] | Req [N] | [expected failure] | [expected pass] | + +## Domain Context +- Engineering domain: [from agent.md] +- Build system: [from agent.md] +- Test framework: [from agent.md] +``` + +### .deepwork/tmp/engineering_issue_url.md + +A single-line file containing the URL of the created engineering issue. + +**Structure**: +``` +https://github.com/owner/repo/issues/123 +``` + +## Quality Criteria + +- Every product requirement maps to at least one implementation task +- Test definitions cover all requirements with explicit red/green states +- The engineering issue is self-contained enough to execute without re-reading the product issue +- The issue was created on the platform with proper labels and links +- Domain-specific conventions from agent.md are reflected in the plan From 8c87856d22ca419c76ff8ed66b5cd78f5f0e8574 Mon Sep 17 00:00:00 2001 From: Nicholas Romero Date: Tue, 24 Mar 2026 16:28:05 -0500 Subject: [PATCH 2/3] =?UTF-8?q?refactor(engineer):=20apply=20review=20feed?= =?UTF-8?q?back=20=E2=80=94=20trim=20step=20files,=20update=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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) --- AGENTS.md | 6 +- doc/architecture.md | 15 ++- .../standard_jobs/engineer/.deepreview | 76 ++++++++++++++ .../standard_jobs/engineer/requirements.md | 23 +++-- .../engineer/steps/check_agent_md.md | 98 +++++-------------- .../engineer/steps/check_context.md | 73 +++----------- .../engineer/steps/doctor_report.md | 90 +++++------------ .../engineer/steps/finalize_pr.md | 98 +++++-------------- .../engineer/steps/green_implementation.md | 89 ++++------------- .../engineer/steps/initialize_branch.md | 55 ++--------- .../engineer/steps/product_sync.md | 71 +++----------- .../standard_jobs/engineer/steps/red_tests.md | 77 +++------------ .../engineer/steps/translate_issue.md | 73 +++----------- 13 files changed, 271 insertions(+), 573 deletions(-) create mode 100644 src/deepwork/standard_jobs/engineer/.deepreview diff --git a/AGENTS.md b/AGENTS.md index 0fbe57c0..a6c259d5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,6 +39,7 @@ 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) **Editing rules**: - Source of truth is ALWAYS in `src/deepwork/standard_jobs/` @@ -104,7 +105,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) @@ -221,7 +223,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 diff --git a/doc/architecture.md b/doc/architecture.md index d7c6eae6..cc9d768e 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -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 @@ -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 — step instructions include domain adaptation tables for software, hardware/CAD, firmware, and documentation projects. 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: diff --git a/src/deepwork/standard_jobs/engineer/.deepreview b/src/deepwork/standard_jobs/engineer/.deepreview new file mode 100644 index 00000000..8da22cda --- /dev/null +++ b/src/deepwork/standard_jobs/engineer/.deepreview @@ -0,0 +1,76 @@ +job_definition_review: + 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. + + ## 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 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 + + ## 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 diff --git a/src/deepwork/standard_jobs/engineer/requirements.md b/src/deepwork/standard_jobs/engineer/requirements.md index 22febc19..6a6d4f35 100644 --- a/src/deepwork/standard_jobs/engineer/requirements.md +++ b/src/deepwork/standard_jobs/engineer/requirements.md @@ -1,5 +1,9 @@ # Engineer Job: RFC 2119 Requirements Specification +This specification defines the normative requirements for the engineer job's +`implement` and `doctor` workflows. The term "engineer" refers to the agent or +human executing the workflow. + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. @@ -7,6 +11,8 @@ interpreted as described in RFC 2119. Note: All general version control operations SHALL adhere to the current established repository standards, beyond the explicit strictures defined below. +## Implement workflow requirements + ## 1. Product and engineering issue delineation The workflow MUST initiate with a high-level Product Issue containing the @@ -14,9 +20,9 @@ overarching user story and functional RFC 2119 requirements. An engineer MUST translate this Product Issue into a distinct Engineering Issue. -The Engineering Issue REQUIRED payloads include the definitive implementation -plan, applicable schematics or CAD snippets, and explicit definitions of -expected red and green test states. +The Engineering Issue MUST include the following payloads: the definitive +implementation plan, applicable schematics or CAD snippets, and explicit +definitions of expected red and green test states. ## 2. Version control initialization @@ -51,11 +57,12 @@ finished and pushed to the remote branch. ## 5. Artifact generation and continuous integration -The automated Continuous Integration (CI) system MUST capture visual -representations of structural or interface alterations upon a successful green -state, and MUST include any of the following that are relevant to the domain: +The engineer MUST verify that the CI system produces visual representations of +structural or interface alterations upon a successful green state. These +artifacts MUST include any of the following that are relevant to the domain: rendered STLs, compiled schematics, localized DOM snapshots, or equivalent -visual artifacts. +visual artifacts. If the CI system does not produce the expected artifacts, the +engineer MUST document the gap and manually capture equivalents. ## 6. Pull request finalization and handoff @@ -79,6 +86,8 @@ explicit, immutable links to the merged PR(s) and closed Engineering Issue(s), ensuring product managers maintain up-to-date visibility without parsing engineering telemetry. +## Doctor workflow requirements + ## 8. Contextual awareness and the doctor workflow To maintain a project-agnostic shared workflow, every repository MUST contain an diff --git a/src/deepwork/standard_jobs/engineer/steps/check_agent_md.md b/src/deepwork/standard_jobs/engineer/steps/check_agent_md.md index 9a0f1593..785630fd 100644 --- a/src/deepwork/standard_jobs/engineer/steps/check_agent_md.md +++ b/src/deepwork/standard_jobs/engineer/steps/check_agent_md.md @@ -1,60 +1,27 @@ # Check Agent Context File -## Objective - -Verify that agent.md (or equivalent domain documentation) exists at the repository root, -declares the engineering domain, and provides build/test/parse instructions for automated agents. - -## Task - -Audit the repository for the presence and completeness of its agent context file. This is the -foundational check — without a valid agent.md, the `implement` workflow cannot adapt to the -project's domain. - -### Process - -1. **Locate the agent context file** - - Check for common names at the repository root: - - `agent.md`, `AGENT.md` - - `AGENTS.md` - - `CLAUDE.md` (if it contains agent-relevant content, not just a symlink) - - `.claude/CLAUDE.md` (Claude Code project instructions) - - Check if any of these are symlinks and resolve them - - Record which file(s) were found and their paths - -2. **Check domain declaration** - - The file MUST explicitly define the project's engineering domain - - Valid domains include but are not limited to: web application, API service, mobile app, - CAD/mechanical, PCB/electronics, firmware/embedded, documentation site, data pipeline, - infrastructure/IaC, monorepo (with sub-domains) - - Record whether the domain is declared and what it is - -3. **Check agent instructions** - - The file MUST contain instructions for automated agents on how to: - - **Parse**: How to read/navigate the codebase (project structure, key files) - - **Build**: How to build or compile the project - - **Test**: How to run the test suite - - Record which instruction categories are present and which are missing - -4. **Check for CODEOWNERS** - - Check for a CODEOWNERS file in standard locations: - - `CODEOWNERS`, `.github/CODEOWNERS`, `docs/CODEOWNERS` (GitHub) - - Forgejo/Gitea equivalents if applicable - - If present, verify it contains at least one rule - - CODEOWNERS is REQUIRED for automatic reviewer assignment when PRs are undrafted - (Req 6) — its absence is a failure - -5. **Check for common issues** - - Empty or stub file (exists but has no real content) - - Circular symlinks - - References to files that don't exist - - Outdated information (e.g., references to deleted directories) +Verify that agent.md (or equivalent) exists, declares the engineering domain, provides +build/test/parse instructions, and that CODEOWNERS is configured. + +## Process + +1. **Locate the agent context file** — check common locations at the repository root: + `agent.md`, `AGENT.md`, `AGENTS.md`, `CLAUDE.md`, `.claude/CLAUDE.md`. + Resolve any symlinks. Record which file(s) were found. +2. **Check domain declaration** — the file MUST explicitly define the project's engineering + domain (e.g., web application, CAD/mechanical, firmware/embedded, documentation site) +3. **Check agent instructions** — verify the file contains instructions for: + - **Parse**: How to navigate the codebase (project structure, key files) + - **Build**: How to build or compile the project + - **Test**: How to run the test suite +4. **Check CODEOWNERS** — look in `CODEOWNERS`, `.github/CODEOWNERS`, `docs/CODEOWNERS`. + CODEOWNERS is REQUIRED for automatic reviewer assignment when PRs are undrafted (Req 6). +5. **Check for issues** — empty/stub files, circular symlinks, references to nonexistent files ## Output Format ### .deepwork/tmp/agent_md_audit.md -**Structure**: ```markdown # Agent Context File Audit @@ -62,41 +29,28 @@ project's domain. - File found: yes/no - Path: [path or "not found"] - Is symlink: yes/no → [target] -- Format: [markdown/yaml/other] ## Domain Declaration -- Domain declared: yes/no -- Domain: [declared domain or "not declared"] -- Specificity: [specific/vague/missing] +- Declared: yes/no +- Domain: [domain or "not declared"] ## Agent Instructions | Category | Present | Details | |----------|---------|---------| -| Parse/Navigate | yes/no | [brief description or "missing"] | -| Build | yes/no | [brief description or "missing"] | -| Test | yes/no | [brief description or "missing"] | +| Parse/Navigate | yes/no | [brief or "missing"] | +| Build | yes/no | [brief or "missing"] | +| Test | yes/no | [brief or "missing"] | ## CODEOWNERS - File found: yes/no - Path: [path or "not found"] -- Rules defined: [N rules or "empty"] +- Rules defined: [N or "empty"] -## Issues Found -- [Issue 1: description] -- [Issue 2: description] -- [none] +## Issues +- [list or "none"] ## Overall Status: [PASS/FAIL] -- Failures: [list of failed checks or "none"] ## Referenced Files -[List of files referenced by agent.md that will be checked in the next step] +[list of files to check in next step] ``` - -## Quality Criteria - -- All common agent file locations are checked -- Symlinks are resolved and validated -- Domain declaration is checked for specificity (not just presence) -- Build, test, and parse instructions are each independently verified -- Issues are specific and actionable diff --git a/src/deepwork/standard_jobs/engineer/steps/check_context.md b/src/deepwork/standard_jobs/engineer/steps/check_context.md index 40eb6419..cfbb8f55 100644 --- a/src/deepwork/standard_jobs/engineer/steps/check_context.md +++ b/src/deepwork/standard_jobs/engineer/steps/check_context.md @@ -1,83 +1,40 @@ # Check Supporting Context Files -## Objective +Verify that files referenced by agent.md are present, correctly linked, and syntactically +valid. If agent.md was not found, report that context files cannot be checked. -Verify that supporting context files referenced by agent.md are present, correctly linked, -and syntactically valid. +## Process -## Task - -Follow every reference from the agent context file and verify the referenced files exist -and are well-formed. This catches broken links, missing files, and syntax errors that would -cause the `implement` workflow to fail or produce incorrect results. - -### Process - -1. **Extract references from agent.md audit** - - Read the `agent_md_audit.md` from the previous step - - Collect the list of referenced files identified there - - If agent.md was not found, report that no context files can be checked and note - that agent.md must be created first - -2. **Check each referenced file** - - For each file reference: - - Verify the file exists at the referenced path - - If it's a symlink, verify the target exists - - If it's a relative path, resolve it relative to agent.md's location - - Check that the file is not empty (zero bytes) - -3. **Validate syntax** - - For each file that exists, validate based on its extension: - - `.yml` / `.yaml`: Valid YAML (parseable without errors) - - `.json`: Valid JSON - - `.md`: Valid Markdown (no broken internal links within the file) - - `.toml`: Valid TOML - - `.nix`: Basic syntax check (balanced braces/brackets) - - For files with no recognized extension, skip syntax validation - -4. **Check for orphaned context files** - - Look for common context file patterns near agent.md that are NOT referenced: - - `CONTRIBUTING.md`, `ARCHITECTURE.md`, `DEVELOPMENT.md` - - `.editorconfig`, `.tool-versions`, `flake.nix` - - These are informational — report them as "available but unreferenced" (not failures) +1. Read `agent_md_audit.md` from the previous step and collect the list of referenced files +2. For each reference: verify it exists, resolve symlinks, check it is non-empty +3. Validate syntax by extension: `.yml`/`.yaml` (valid YAML), `.json` (valid JSON), + `.md` (no broken internal links), `.toml` (valid TOML), `.nix` (balanced braces) +4. Note any unreferenced context files near agent.md (`CONTRIBUTING.md`, `ARCHITECTURE.md`, + `.editorconfig`, `flake.nix`, etc.) as informational — not failures ## Output Format ### .deepwork/tmp/context_audit.md -**Structure**: ```markdown # Context File Audit ## Source -- Agent context file: [path from audit] -- Agent context status: [PASS/FAIL from previous step] +- Agent context file: [path] +- Agent context status: [PASS/FAIL] ## Referenced Files | # | Path | Exists | Symlink | Syntax | Status | |---|------|--------|---------|--------|--------| | 1 | [path] | yes/no | yes→[target]/no | valid/invalid/skipped | PASS/FAIL | -| 2 | [path] | yes/no | no | valid | PASS | -## Issues Found -- [Issue 1: description and remediation] -- [none] +## Issues +- [list or "none"] ## Unreferenced Context Files -- [path] — [brief description of what it contains] -- [none found] +- [path] — [description] ## Overall Status: [PASS/FAIL] -- Referenced files checked: [N] -- Passed: [N] -- Failed: [N] +- Checked: [N], Passed: [N], Failed: [N] ``` - -## Quality Criteria - -- Every file reference from agent.md is checked -- Symlinks are fully resolved -- Syntax validation matches the file format -- Broken references include specific paths for remediation -- Unreferenced context files are noted as informational, not failures diff --git a/src/deepwork/standard_jobs/engineer/steps/doctor_report.md b/src/deepwork/standard_jobs/engineer/steps/doctor_report.md index 41d3b211..8e525833 100644 --- a/src/deepwork/standard_jobs/engineer/steps/doctor_report.md +++ b/src/deepwork/standard_jobs/engineer/steps/doctor_report.md @@ -1,48 +1,25 @@ # Doctor Report -## Objective - -Compile findings from the agent.md and context file audits into a consolidated pass/fail -report with specific remediation instructions for any failures. - -## Task - -Synthesize the previous audit steps into a single actionable report. The report serves two -audiences: the human developer who needs to fix issues, and the `implement` workflow which -needs to know if the repository is ready for automated engineering execution. - -### Process - -1. **Read both audit files** - - Read `agent_md_audit.md` for agent context file findings - - Read `context_audit.md` for supporting file findings - - Collect all PASS and FAIL statuses - -2. **Compile the consolidated report** - - Organize findings by check category - - For each failed check, provide: - - What is wrong - - Why it matters (which workflow step would fail or produce bad results) - - Specific remediation steps (commands to run, content to add, files to create) - - For passing checks, confirm with a brief status line - -3. **Add cross-cutting recommendations** - - If labels, branch protection, or milestones need attention, recommend the `repo` - library job's `doctor` workflow — do not duplicate that job's scope - - If the repository lacks CI configuration, note this as it affects artifact generation - (Req 5) - - If the repository is a monorepo, note that each sub-project may need its own context - -4. **Determine overall readiness** - - READY: All checks pass — the `implement` workflow can proceed - - NOT READY: One or more critical checks fail — remediation is needed first - - PARTIAL: Non-critical issues exist but `implement` can proceed with caveats +Compile findings from agent.md and context file audits into a pass/fail report with +remediation instructions. Serves two audiences: the developer fixing issues, and the +`implement` workflow checking readiness. + +## Process + +1. Read `agent_md_audit.md` and `context_audit.md`; collect all PASS/FAIL statuses +2. For each failed check, provide: what is wrong, which workflow step would fail, and + specific remediation steps +3. Cross-cutting recommendations: + - If labels/branch protection/milestones need attention, recommend `repo` library job's + `doctor` workflow — do not duplicate that scope + - If CI is not configured, note the impact on artifact generation (Req 5) +4. Determine overall readiness: READY (all pass), NOT READY (critical failures), + or PARTIAL (non-critical issues, implement can proceed with caveats) ## Output Format ### .deepwork/tmp/doctor_report.md -**Structure**: ```markdown # Engineer Doctor Report @@ -52,40 +29,27 @@ needs to know if the repository is ready for automated engineering execution. | # | Check | Status | Details | |---|-------|--------|---------| -| 1 | Agent context file exists | PASS/FAIL | [brief detail] | -| 2 | Engineering domain declared | PASS/FAIL | [brief detail] | -| 3 | Build instructions present | PASS/FAIL | [brief detail] | -| 4 | Test instructions present | PASS/FAIL | [brief detail] | -| 5 | Parse/navigate instructions present | PASS/FAIL | [brief detail] | +| 1 | Agent context file exists | PASS/FAIL | [detail] | +| 2 | Engineering domain declared | PASS/FAIL | [detail] | +| 3 | Build instructions present | PASS/FAIL | [detail] | +| 4 | Test instructions present | PASS/FAIL | [detail] | +| 5 | Parse/navigate instructions present | PASS/FAIL | [detail] | | 6 | Referenced files exist | PASS/FAIL | [N/N passed] | | 7 | Referenced files valid syntax | PASS/FAIL | [N/N passed] | | 8 | CODEOWNERS file present | PASS/FAIL | [path or "not found"] | -## Remediation Required +## Remediation ### [Check Name] — FAIL **Problem**: [what is wrong] -**Impact**: [which workflow step would fail] -**Fix**: -1. [specific step] -2. [specific step] - -### [Another Check] — FAIL -... +**Impact**: [which step would fail] +**Fix**: [specific steps] ## Recommendations -- [recommendation about repo job, CI, or other improvements] +- [cross-cutting recommendations] ## Next Steps -- [If READY]: Run `engineer/implement` workflow to begin engineering work -- [If NOT READY]: Fix the issues listed above, then re-run `engineer/doctor` -- [If PARTIAL]: [specific caveats for proceeding] +- [READY]: Run `engineer/implement` to begin +- [NOT READY]: Fix issues above, re-run `engineer/doctor` +- [PARTIAL]: [caveats] ``` - -## Quality Criteria - -- Every check from both audit steps is represented in the summary table -- Failed checks have specific, actionable remediation instructions -- The report distinguishes between critical failures and non-critical recommendations -- Cross-cutting recommendations reference existing jobs (e.g., `repo/doctor`) rather than duplicating scope -- The overall status accurately reflects whether the `implement` workflow can proceed diff --git a/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md b/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md index 634ac75e..ed941aff 100644 --- a/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md +++ b/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md @@ -1,105 +1,53 @@ # Finalize PR with Artifacts -## Objective - -Ensure CI generates visual artifacts, populate the PR #demo section with those artifacts, -document handoff notes, and verify all checkboxes are complete before requesting review. - -## Task - -Prepare the PR for peer review by ensuring all automated artifacts are captured, the demo -section showcases the changes, and any downstream implications are documented. - -### Process - -1. **Verify CI artifact generation** - - Confirm the CI pipeline ran successfully on the latest push - - Check that visual artifacts were generated (domain-appropriate): - - Software: DOM snapshots, screenshot diffs, API response samples - - Hardware/CAD: rendered STLs, compiled schematics, Gerber previews - - Firmware: logic analyzer traces, memory maps - - Docs: PDF renders, HTML previews - - If CI does not generate artifacts, document this as a gap and manually capture equivalents - -2. **Populate the #demo section** - - Add the automatically generated visual artifacts to the PR's `## Demo` section - - Include before/after comparisons where applicable - - Add brief captions explaining what each artifact shows - -3. **Document handoff notes** - - If the implementation unblocks downstream work, document in a `## Handoff` section: - - What is unblocked and for whom - - Any staging/production verification needed - - Migration steps if applicable - - If no downstream implications exist, note this explicitly - -4. **Final checkbox verification** - - Verify every PR task checkbox is checked - - Cross-reference against the engineering issue's implementation plan - - Ensure the branch is up to date with the base branch - -5. **Undraft and request review** - - MUST transition the PR from draft to ready-for-review state - - GitHub: `gh pr ready [PR-URL]` - - Forgejo/Gitea: equivalent API call to remove WIP/draft status - - Code owners (defined in `CODEOWNERS` or equivalent) are automatically requested as - reviewers when the PR is undrafted — verify this happened - - If the platform does not support automatic code owner assignment, manually request - the appropriate reviewers - - Note: the PR SHALL NOT be merged until peer review validates artifacts and checkboxes - -### Domain Adaptation - -| Concept | Software | Hardware/CAD | Firmware | Docs | -|------------------|-----------------------|------------------------|-----------------------|----------------------| -| CI artifacts | DOM snapshots, tests | STL renders, DRC | HIL logs, .hex size | PDF render, link check | -| Demo section | Screenshots, GIFs | 3D model views | Logic traces | Before/after content | -| Handoff | Deploy instructions | BOM update notes | Flash instructions | Publish instructions | +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 +3. **Document handoff** — if the implementation unblocks downstream work or needs + staging/production verification, add a `## Handoff` section; otherwise note "none" +4. **Verify checkboxes** — confirm every PR task checkbox is checked and matches the branch state +5. **Undraft and request review**: + - MUST transition the PR from draft to ready-for-review (`gh pr ready [PR-URL]`) + - Code owners (from `CODEOWNERS`) are automatically requested as reviewers — verify this happened + - If the platform lacks automatic code owner assignment, manually request reviewers + - The PR SHALL NOT be merged until peer review validates artifacts and checkboxes ## Output Format ### .deepwork/tmp/pr_finalization.md -**Structure**: ```markdown # PR Finalization ## CI Status - Pipeline: [pass/fail/pending] -- Artifact generation: [available/not available/manual] +- Artifacts: [available/not available/manual] ## Visual Artifacts | Artifact | Type | Location | |----------|------|----------| -| [artifact name] | [STL render/screenshot/trace/etc.] | [URL or path] | +| [name] | [type] | [URL or path] | ## Demo Section - Updated: yes/no - Artifacts included: [N] -- Before/after comparisons: yes/no/not applicable ## Handoff - Downstream implications: [yes/no] - Details: [description or "none"] -- Staging verification needed: [yes/no] -## Checkbox State -- Total checkboxes: [N] -- Checked: [N] -- All synchronized: yes/no +## Checkboxes +- Total: [N], Checked: [N], Synchronized: yes/no -## Review Readiness +## Review - PR undrafted: yes/no - Code owner reviewers requested: [names or "not configured"] -- Additional reviewers: [names or "none"] - Base branch up to date: yes/no ``` - -## Quality Criteria - -- CI artifacts are verified or manually captured -- The PR #demo section displays visual artifacts relevant to the domain -- Handoff notes document downstream implications (or explicitly state there are none) -- All PR checkboxes are checked and synchronized -- The PR is undrafted (transitioned to ready for review) -- Code owner reviewers are requested (or noted as not configured) diff --git a/src/deepwork/standard_jobs/engineer/steps/green_implementation.md b/src/deepwork/standard_jobs/engineer/steps/green_implementation.md index 85217663..12f4ab83 100644 --- a/src/deepwork/standard_jobs/engineer/steps/green_implementation.md +++ b/src/deepwork/standard_jobs/engineer/steps/green_implementation.md @@ -1,94 +1,47 @@ # Implement to Pass Tests -## Objective +Implement the necessary logic, parameters, or configuration to transition all tests from +red to green. Keep PR checkboxes synchronized with progress throughout. -Implement the necessary logic, hardware parameters, or configuration changes to transition -all tests from red to green. Keep PR checkboxes synchronized with progress throughout. +## Process -## Task - -Execute the implementation plan from the engineering issue, working test by test until the -entire suite passes. Maintain continuous state synchronization between the worktree and the -PR throughout. - -### Process - -1. **Review the implementation plan and test manifest** - - Read the engineering issue's implementation plan - - Read the test manifest to understand what each test expects - - Plan the implementation order (dependencies between tasks may dictate sequence) - -2. **Implement task by task** - - For each implementation task: - - Write the necessary code, configuration, or design changes - - Run the relevant tests to verify they transition from red to green - - Commit with a conventional commit message: `feat(scope): implement [task description]` - - Push to the remote branch - - **Immediately update the PR checkbox** for the completed task - -3. **Verify all tests green** - - Run the full test suite after all tasks are implemented - - Capture the test output showing all tests passing - - If any tests remain red, investigate and fix before proceeding - -4. **Synchronize PR state** - - Verify all PR checkboxes reflect the current branch state - - Update the PR description if the implementation diverged from the original plan - - Add a comment summarizing the implementation if noteworthy decisions were made - -### Domain Adaptation - -| Concept | Software | Hardware/CAD | Firmware | Docs | -|------------------|-----------------------|------------------------|-----------------------|----------------------| -| Implementation | Code changes | Schematic/model edits | Register/driver code | Content writing | -| Green state | Tests pass | DRC clean | Tests pass | Links valid, lint clean | -| Commit granularity | Per logical change | Per design change | Per module | Per section | +1. Review the implementation plan and test manifest to plan execution order +2. For each task: + - Write the necessary changes + - Run relevant tests to verify red-to-green transition + - Commit: `feat(scope): implement [task description]` + - Push to remote + - **Immediately update the PR checkbox** for the completed task +3. Run the full test suite and confirm all tests pass +4. Verify all PR checkboxes reflect the current branch state ## Output Format ### .deepwork/tmp/implementation_summary.md -**Structure**: ```markdown # Implementation Summary ## Overview -- Total tasks: [N] -- Tasks completed: [N] +- Tasks completed: [N]/[total] - All tests green: yes/no -## Implementation Details +## Tasks ### Task 1: [task name] - Requirement: Req [N] - Changes: [files modified/created] - Test result: PASS - Commit: [sha] -- PR checkbox: updated - -### Task 2: [task name] -... -## Test Suite Output -``` -[paste of test runner output showing all tests passing] -``` +## Test Output +[paste of test runner output showing all passes] ## PR State -- All checkboxes synchronized: yes/no -- Checkboxes checked: [N]/[total] -- Implementation divergences: [none, or description of changes from original plan] +- Checkboxes synchronized: yes/no +- Checked: [N]/[total] +- Divergences from plan: [none, or description] -## Commits (in order) -1. [sha] — [commit message] -2. [sha] — [commit message] -... +## Commits +1. [sha] — [message] ``` - -## Quality Criteria - -- All tests from the test manifest have transitioned to green -- PR checkboxes are immediately updated as each task completes -- Each implementation change is committed and pushed individually -- No unrelated changes are included in the implementation -- The implementation follows the project's conventions from agent.md diff --git a/src/deepwork/standard_jobs/engineer/steps/initialize_branch.md b/src/deepwork/standard_jobs/engineer/steps/initialize_branch.md index abc32aab..27e74f7a 100644 --- a/src/deepwork/standard_jobs/engineer/steps/initialize_branch.md +++ b/src/deepwork/standard_jobs/engineer/steps/initialize_branch.md @@ -1,51 +1,22 @@ # Initialize Branch and Draft PR -## Objective +Create a dedicated git branch or worktree for the engineering issue, commit the specification +before any implementation code, and open a draft PR using the repository's PR template. -Create a dedicated git worktree or branch for the engineering issue, commit the specification, -and open a draft PR using the repository's standardized PR template. +## Process -## Task - -Set up the version control foundation for engineering work. The specification must be committed -before any implementation code, and a draft PR must exist immediately to enable continuous -synchronization. - -### Process - -1. **Create a dedicated branch or worktree** - - Branch naming: follow the repository's conventions (e.g., `feat/issue-123-description`) - - If the repository uses worktrees, create one; otherwise create a branch - - Ensure the branch is based on the latest default branch - -2. **Commit the engineering specification** - - Add the engineering issue content to the branch (e.g., as a spec file, or as the commit message) - - This commit MUST happen before any implementation code - - Use a conventional commit message: `docs(engineer): add engineering spec for #[issue-number]` - -3. **Open a draft PR** - - Use the repository's standardized PR template - - Title: follow repository conventions (e.g., `feat(scope): description`) +1. Create a branch based on the latest default branch, following the repository's naming conventions +2. Commit the engineering specification — this MUST happen before any implementation code + - Use a conventional commit: `docs(engineer): add engineering spec for #[issue-number]` +3. Open a draft PR using the repository's standardized template: - Link the PR to the engineering issue - Populate the task checklist from the engineering issue's implementation plan - - Mark the PR as draft - -4. **Record the branch context** - - Document the branch name, PR URL, and initial commit SHA - - This context is consumed by subsequent steps - -### Domain Adaptation - -| Concept | Software | Hardware/CAD | Firmware | Docs | -|------------------|---------------------|----------------------|---------------------|---------------------| -| Spec commit | API contract/schema | Design doc/BOM | Register map | Content outline | -| PR template | Code PR template | Design review form | HW/FW PR template | Doc review template | +4. Record the branch name, PR URL, and initial commit SHA ## Output Format ### .deepwork/tmp/branch_context.md -**Structure**: ```markdown # Branch Context @@ -61,18 +32,8 @@ synchronization. ## Engineering Issue - URL: [engineering-issue-url] -- Linked in PR: yes/no ## Task Checklist (from PR) - [ ] Task 1: [description] - [ ] Task 2: [description] -... ``` - -## Quality Criteria - -- Branch is based on the latest default branch -- Engineering spec was committed before any implementation code -- Draft PR uses the repository's standardized template -- PR is linked to the engineering issue -- Task checklist is populated from the implementation plan diff --git a/src/deepwork/standard_jobs/engineer/steps/product_sync.md b/src/deepwork/standard_jobs/engineer/steps/product_sync.md index b97eb5d0..21a2cbb8 100644 --- a/src/deepwork/standard_jobs/engineer/steps/product_sync.md +++ b/src/deepwork/standard_jobs/engineer/steps/product_sync.md @@ -1,61 +1,24 @@ # Synchronize Product Issue -## Objective - After PR merge and engineering issue closure, author a formal comment on the parent -product issue documenting completed user stories with immutable links to the merged PR -and closed engineering issue. - -## Task - -Close the traceability loop by updating the product issue so product managers have -up-to-date visibility without parsing engineering telemetry. This step is designed to -run after the PR has been merged — if the PR is still under review, pause and resume -this step later. - -### Process - -1. **Verify prerequisites** - - Confirm the PR has been merged (check PR state) - - Confirm the engineering issue is closed (check issue state) - - If either is still open, inform the user and pause — this step can be resumed later - via `go_to_step` - -2. **Gather immutable links** - - Merged PR URL (the canonical merged-state URL, not a draft URL) - - Closed engineering issue URL - - Any relevant commit SHAs for key changes +product issue documenting completed user stories with immutable links. -3. **Identify completed user stories** - - Cross-reference the engineering issue's implementation plan with the product issue's - user story and requirements - - Summarize which high-level user stories were addressed - - Note any requirements that were partially addressed or deferred +## Process -4. **Author the product issue comment** - - Post a formal comment on the parent product issue - - The comment MUST include: - - Which user stories were completed - - Immutable links to the merged PR and closed engineering issue - - Any deferred items or follow-up needed - - The comment SHOULD be written for a product manager audience (no engineering jargon) - -5. **Record the synchronization** - - Document what was posted and when - -### Domain Adaptation - -| Concept | Software | Hardware/CAD | Firmware | Docs | -|------------------|-----------------------|------------------------|-----------------------|----------------------| -| "Merged PR" | Code PR merged | Design PR merged | FW PR merged | Content PR merged | -| User story | Feature/fix | Design requirement | HW interface need | Content requirement | -| Follow-up | Tech debt, next phase | Prototype feedback | Integration test plan | Review feedback | +1. **Verify prerequisites** — confirm the PR is merged and the engineering issue is closed. + If either is still open, inform the user and pause — resume via `go_to_step` after merge. +2. Gather immutable links: merged PR URL, closed engineering issue URL, key commit SHAs +3. Summarize which high-level user stories were addressed; note any deferred items +4. Post a formal comment on the parent product issue: + - Which user stories were completed + - Immutable links to merged PR and closed engineering issue + - Any deferred items or follow-up needed + - Written for a product manager audience (no engineering jargon) ## Output Format ### .deepwork/tmp/product_sync_record.md -**Structure**: ```markdown # Product Sync Record @@ -64,12 +27,12 @@ this step later. - Engineering issue closed: yes/no — [issue URL] ## Comment Posted -- Product issue: [product issue URL] +- Product issue: [URL] - Timestamp: [ISO 8601] ## Comment Content --- -[The exact text of the comment that was posted] +[exact text posted] --- ## Traceability @@ -77,11 +40,3 @@ this step later. - Deferred items: [list or "none"] - Follow-up needed: [yes/no — description] ``` - -## Quality Criteria - -- The product issue comment was posted only after the PR was merged and engineering issue closed -- The comment includes immutable links to the merged PR and closed engineering issue -- User stories completed are summarized in product-manager-friendly language -- Any deferred items are explicitly documented -- The comment provides enough context for product visibility without engineering telemetry diff --git a/src/deepwork/standard_jobs/engineer/steps/red_tests.md b/src/deepwork/standard_jobs/engineer/steps/red_tests.md index 0db8cdd0..622e8fa1 100644 --- a/src/deepwork/standard_jobs/engineer/steps/red_tests.md +++ b/src/deepwork/standard_jobs/engineer/steps/red_tests.md @@ -1,86 +1,41 @@ # Write Failing Tests -## Objective - Implement new failing (red) tests or verify existing tests against the new requirements. -Each test must explicitly reference a specific requirement from the engineering issue. - -## Task - -Establish the test-driven development boundary. All tests must exist and fail before any -implementation code is written. This ensures requirements drive the implementation, not -the other way around. - -### Process - -1. **Review the engineering issue's test definitions** - - Read the test definitions table from `engineering_issue.md` - - Identify which tests need to be created vs. which existing tests can be reused - - Confirm the test framework and conventions from agent.md - -2. **Implement or verify tests** - - For each requirement, either: - - Write a new failing test that validates the requirement - - Verify an existing test covers the requirement and would fail without the new implementation - - Each test MUST include a comment or annotation referencing the specific requirement - (e.g., `# Req 3: Each test must reference a specific requirement`) - -3. **Verify red state** - - Run the test suite and confirm all new/modified tests fail - - Capture the test output showing the failures - - If any test unexpectedly passes, investigate — it may indicate the requirement is already met +Each test MUST reference a specific requirement from the engineering issue. All tests MUST +fail before any implementation begins. -4. **Commit the failing tests** - - Commit tests separately from implementation: `test(scope): add failing tests for #[issue-number]` - - Push to the remote branch - - Update PR checkboxes for test-related tasks +## Process -5. **Create the test manifest** - - Document each test, its requirement reference, and its red state verification - -### Domain Adaptation - -| Concept | Software | Hardware/CAD | Firmware | Docs | -|------------------|-----------------------|------------------------|-----------------------|----------------------| -| Test file | `test_*.py`, `*.test.ts` | DRC rule file | `test_*.c`, HIL script | `linkcheck.py`, lint config | -| Test runner | pytest, jest, cargo | KiCad DRC, FreeCAD | ceedling, Unity | sphinx linkcheck, markdownlint | -| Req reference | Docstring/comment | Rule comment | Test name/comment | Config comment | -| Red state | Test fails | DRC violation | Assert fails | Link broken/lint error | +1. Review the test definitions from `engineering_issue.md` — identify which tests to create vs. reuse +2. For each requirement, write a new failing test or verify an existing test covers it + - Include a comment or annotation referencing the requirement (e.g., `# Req 3: ...`) +3. Run the test suite and confirm all new/modified tests fail; investigate any unexpected passes +4. Commit tests separately from implementation: `test(scope): add failing tests for #[issue-number]` +5. Push to the remote branch and update PR checkboxes for test-related tasks ## Output Format ### .deepwork/tmp/test_manifest.md -**Structure**: ```markdown # Test Manifest -## Test Suite Summary +## Summary - Framework: [test framework] -- Total new tests: [N] -- Total verified existing tests: [N] +- New tests: [N] +- Verified existing: [N] - Red state confirmed: yes/no -## Test Details +## Tests | # | Test | File | Requirement | Type | Red State | |---|------|------|-------------|------|-----------| -| 1 | [test name] | [file:line] | Req [N] | new | FAIL: [failure reason] | -| 2 | [test name] | [file:line] | Req [N] | existing | FAIL: [failure reason] | +| 1 | [test name] | [file:line] | Req [N] | new | FAIL: [reason] | +| 2 | [test name] | [file:line] | Req [N] | existing | FAIL: [reason] | ## Test Output -``` [paste of test runner output showing failures] -``` ## Commits -- Test commit: [sha] — [commit message] +- [sha] — [commit message] ``` - -## Quality Criteria - -- Every requirement from the engineering issue has at least one test -- All new tests fail (red state) before implementation begins -- Each test references its requirement explicitly in code -- Tests were committed as a separate commit from implementation -- Test manifest accurately reflects the current state diff --git a/src/deepwork/standard_jobs/engineer/steps/translate_issue.md b/src/deepwork/standard_jobs/engineer/steps/translate_issue.md index dc9d8901..d8054f92 100644 --- a/src/deepwork/standard_jobs/engineer/steps/translate_issue.md +++ b/src/deepwork/standard_jobs/engineer/steps/translate_issue.md @@ -1,56 +1,23 @@ # Translate Product Issue to Engineering Issue -## Objective +Transform the product issue into a distinct engineering issue with implementation plan, +test definitions (red/green states), and traceability links. -Read the product issue, extract its requirements, and create a distinct engineering issue -containing the implementation plan, test definitions, and traceability links. +## Process -## Task - -Transform a high-level product issue (user story + requirements) into a concrete engineering -issue that an agent or engineer can execute against. The engineering issue is a separate -artifact — not a copy of the product issue. - -### Process - -1. **Read the product issue** - - Fetch the product issue using its URL or identifier - - Extract the user story and all functional requirements - - Identify any acceptance criteria, constraints, or non-functional requirements - - Note the product issue's labels, milestone, and assignees - -2. **Read the repository's agent.md** - - Determine the project's engineering domain from agent.md (or equivalent) - - Understand the build, test, and deployment conventions - - If agent.md does not exist, warn the user and recommend running the `doctor` workflow first - -3. **Draft the engineering issue** - - Write a definitive implementation plan with actionable tasks - - Define expected red and green test states for each requirement - - Include applicable schematics, CAD snippets, code references, or configuration details - - Map every product requirement to at least one implementation task - -4. **Create the engineering issue on the platform** - - Create a new issue on the git platform (GitHub, Forgejo, etc.) - - Label it with `engineering` - - Link it to the parent product issue - - Assign it to the same milestone if applicable - -### Domain Adaptation - -| Concept | Software | Hardware/CAD | Firmware | Docs | -|----------------------|---------------------|----------------------|---------------------|---------------------| -| Implementation plan | Code changes | Design changes | Register/driver map | Content outline | -| Test definitions | Unit/integration | DRC/simulation | HIL/unit test | Link check/lint | -| Schematics/snippets | API contracts | KiCad/FreeCAD refs | Pinout diagrams | IA diagrams | +1. Fetch the product issue — extract user story, requirements, acceptance criteria, and constraints +2. Read agent.md to determine the engineering domain and build/test conventions; if missing, warn the user and recommend the `doctor` workflow +3. Draft the engineering issue: + - Definitive implementation plan with actionable tasks + - Red and green test state definitions for each requirement + - Domain-appropriate schematics, code references, or configuration details + - Every product requirement mapped to at least one task +4. Create the issue on the git platform, label as `engineering`, link to parent product issue ## Output Format ### .deepwork/tmp/engineering_issue.md -The engineering issue content, structured for both platform posting and step consumption. - -**Structure**: ```markdown # Engineering Issue: [Title] @@ -65,9 +32,6 @@ The engineering issue content, structured for both platform posting and step con - Description: [what to implement] - Files: [expected files to create/modify] -### Task 2: [task name] -... - ## Test Definitions | Test | Requirement | Red State (before) | Green State (after) | @@ -82,17 +46,4 @@ The engineering issue content, structured for both platform posting and step con ### .deepwork/tmp/engineering_issue_url.md -A single-line file containing the URL of the created engineering issue. - -**Structure**: -``` -https://github.com/owner/repo/issues/123 -``` - -## Quality Criteria - -- Every product requirement maps to at least one implementation task -- Test definitions cover all requirements with explicit red/green states -- The engineering issue is self-contained enough to execute without re-reading the product issue -- The issue was created on the platform with proper labels and links -- Domain-specific conventions from agent.md are reflected in the plan +Single-line file containing the URL of the created engineering issue. From 5ab125e48b8e04db5e038ac1a01a14d5a7e97aa6 Mon Sep 17 00:00:00 2001 From: Nicholas Romero Date: Tue, 24 Mar 2026 16:50:56 -0500 Subject: [PATCH 3/3] fix(engineer): address PR review comments 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 --- AGENTS.md | 2 ++ doc/architecture.md | 2 +- .../standard_jobs/engineer/.deepreview | 19 ++++++++++++------- src/deepwork/standard_jobs/engineer/AGENTS.md | 2 +- src/deepwork/standard_jobs/engineer/job.yml | 8 ++++---- .../standard_jobs/engineer/requirements.md | 4 ++-- .../engineer/steps/finalize_pr.md | 4 ++-- 7 files changed, 24 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a6c259d5..c7d18854 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,7 @@ 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) +- `deepwork_reviews` - DeepWork job review and quality control workflows **Editing rules**: - Source of truth is ALWAYS in `src/deepwork/standard_jobs/` @@ -244,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. diff --git a/doc/architecture.md b/doc/architecture.md index cc9d768e..3f80be61 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -628,7 +628,7 @@ DeepWork includes a built-in job called `engineer` for domain-agnostic engineeri - **`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`. +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 diff --git a/src/deepwork/standard_jobs/engineer/.deepreview b/src/deepwork/standard_jobs/engineer/.deepreview index 8da22cda..fa22a5f3 100644 --- a/src/deepwork/standard_jobs/engineer/.deepreview +++ b/src/deepwork/standard_jobs/engineer/.deepreview @@ -1,15 +1,16 @@ job_definition_review: - description: "Review job.yml and step instructions for correctness, completeness, and coherence as a holistic workflow." + 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) and its step instruction files - (steps/*.md) holistically. Check that they form a coherent, well-structured - workflow that an AI agent can execute reliably. + 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 @@ -57,14 +58,18 @@ job_definition_review: - Steps with no meaningful quality checks use `reviews: []` ### 6. Step Instruction Quality - - Each instruction file has clear sections: Objective, Task/Process, - Output Format, and Quality Criteria + - 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 + - Instructions explain how to use file inputs from prior steps and how the + step's outputs will be consumed by later steps. ## Output Format diff --git a/src/deepwork/standard_jobs/engineer/AGENTS.md b/src/deepwork/standard_jobs/engineer/AGENTS.md index 8451e712..49ad212e 100644 --- a/src/deepwork/standard_jobs/engineer/AGENTS.md +++ b/src/deepwork/standard_jobs/engineer/AGENTS.md @@ -32,7 +32,7 @@ engineer/ ## Design Decisions -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 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 diff --git a/src/deepwork/standard_jobs/engineer/job.yml b/src/deepwork/standard_jobs/engineer/job.yml index aff96740..49450519 100644 --- a/src/deepwork/standard_jobs/engineer/job.yml +++ b/src/deepwork/standard_jobs/engineer/job.yml @@ -16,8 +16,8 @@ common_job_info_provided_to_all_steps_at_runtime: | ## Domain Adaptation - 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: | Concept | Software | Hardware/CAD | Firmware | Docs | |-----------------|-------------------|--------------------|-------------------|------------------| @@ -169,7 +169,7 @@ steps: - 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." + 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 @@ -187,7 +187,7 @@ steps: 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." + "Visual Artifacts Present": "The PR ## Demo section displays automatically generated visual artifacts relevant to the domain." "Handoff Documented": "If the implementation unblocks downstream work, handoff notes are documented in the PR." "Checkboxes Complete": "All PR task checkboxes are checked and synchronized with the branch state." "PR Undrafted": "The PR has been undrafted (transitioned to ready for review) and code owner reviewers have been requested." diff --git a/src/deepwork/standard_jobs/engineer/requirements.md b/src/deepwork/standard_jobs/engineer/requirements.md index 6a6d4f35..46494465 100644 --- a/src/deepwork/standard_jobs/engineer/requirements.md +++ b/src/deepwork/standard_jobs/engineer/requirements.md @@ -66,12 +66,12 @@ engineer MUST document the gap and manually capture equivalents. ## 6. Pull request finalization and handoff -The #demo section of the PR MUST display the automatically generated visual +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. +comment or within the `## Handoff` section of the PR. The PR SHALL NOT be merged until peer review validates the visual artifacts and verifies that all synchronized task checkboxes are complete. diff --git a/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md b/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md index ed941aff..bd8393dc 100644 --- a/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md +++ b/src/deepwork/standard_jobs/engineer/steps/finalize_pr.md @@ -1,6 +1,6 @@ # Finalize PR with Artifacts -Ensure CI generates visual artifacts, populate the PR #demo section, document handoff +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 @@ -8,7 +8,7 @@ notes, verify all checkboxes are complete, and undraft the PR for review. 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 +2. **Populate `## Demo`** — add visual artifacts with captions and before/after comparisons where applicable 3. **Document handoff** — if the implementation unblocks downstream work or needs staging/production verification, add a `## Handoff` section; otherwise note "none"