feat(engineer): add requirements workflow for RFC 2119 requirement management

library/jobs/README.md

@@ -16,6 +16,7 @@ This walks you through configuring `DEEPWORK_ADDITIONAL_JOBS_FOLDERS` so the Dee
 
 | Job | Description |
 |-----|-------------|
+| [Engineer](./engineer) | Domain-agnostic engineering execution — TDD from product issue through PR merge, RFC 2119 requirements management, and project setup validation |
 | [Research](./research) | Multi-workflow research suite — deep investigation, quick summaries, material ingestion, and reproduction planning |
 | [Platform Engineer](./platform_engineer) | Incident response, observability, CI/CD, releases, security, cost management, and infrastructure |
 | [Repo](./repo) | Audit and configure repositories — labels, branch protection, milestones, and boards |
@@ -68,6 +69,12 @@ Each job in this library follows the same structure as the `.deepwork/jobs` subf
 library/jobs/
 ├── .deepreview              # Review rules for library job quality
 ├── README.md
+├── engineer/                # Domain-agnostic engineering (implement, requirements, doctor)
+│   ├── job.yml
+│   ├── AGENTS.md            # Agent context and design decisions
+│   ├── CLAUDE.md -> AGENTS.md
+│   ├── requirements.md      # RFC 2119 spec for the job
+│   └── steps/
 ├── platform_engineer/       # Platform engineering workflows
 │   ├── job.yml
 │   ├── AGENTS.md            # Agent context and learnings

library/jobs/engineer/AGENTS.md

@@ -20,6 +20,9 @@ engineer/
     ├── green_implementation.md
     ├── finalize_pr.md
     ├── product_sync.md
+    ├── discover_requirements.md
+    ├── draft_requirements.md
+    ├── validate_requirements.md
     ├── check_agent_md.md
     ├── check_context.md
     └── doctor_report.md
@@ -28,16 +31,35 @@ engineer/
 ## 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
+- **requirements**: 3-step workflow to create or amend RFC 2119 requirements in the project's requirements directory
+- **doctor**: 3-step workflow validating AGENTS.md and domain context files
+
+## Requirements directory
+
+The `requirements` workflow stores requirement files in `./requirements/` by
+default (relative to the repository root). Each file follows the `REQ-NNN-slug.md`
+naming convention with RFC 2119 keywords.
+
+To use a custom path, add a `## Requirements` section to the project's AGENTS.md:
+
+```markdown
+## Requirements
+
+Requirements are stored in `docs/specs/requirements/`.
+```
+
+The workflow reads this section at discovery time. If no override is found, it
+falls back to `./requirements/`.
 
 ## Design Decisions
 
 1. **Domain-agnostic**: Domain adaptation tables (software, hardware, CAD, firmware, docs) live in `job.yml` `common_job_info`; step instructions are written to be domain-agnostic and rely on those tables
 2. **Six implement steps**: Preserves TDD discipline boundary (red tests committed before green implementation)
 3. **product_sync is separate**: Workflow can pause at finalize_pr while PR undergoes human review
-4. **Doctor focuses on agent.md**: Recommends `repo` library job for labels/branch protection/milestones
+4. **Doctor focuses on AGENTS.md**: Recommends `repo` library job for labels/branch protection/milestones
 5. **Requirements bundled**: RFC 2119 spec lives alongside job definition as `requirements.md`
+6. **Self-documenting via requirements.md**: Library jobs are exempt from the DeepWork `specs/` traceability chain. Each library job carries its own RFC 2119 spec as `requirements.md`. This is the authoritative behavioral contract for the job — no corresponding entry in `specs/` is required.
 
 ## Last Updated
-- Date: 2026-03-25
-- From conversation about: Moved from standard_jobs to library/jobs
+- Date: 2026-03-30
+- From conversation about: Added requirements workflow (discover, draft, validate), updated requirements.md with Req 9-12

library/jobs/engineer/job.yml

@@ -11,7 +11,7 @@ common_job_info_provided_to_all_steps_at_runtime: |
   ## 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).
+  in the job directory. Step instructions reference requirements by number (Req 1-12).
   Read `requirements.md` for the full normative text.
 
   ## Domain Adaptation
@@ -53,6 +53,13 @@ workflows:
       - finalize_pr
       - product_sync
 
+  - name: requirements
+    summary: "Create or amend RFC 2119 requirements in the project's requirements directory"
+    steps:
+      - discover_requirements
+      - draft_requirements
+      - validate_requirements
+
   - name: doctor
     summary: "Validate that agent.md and domain context files are present, linked, and valid"
     steps:
@@ -220,6 +227,75 @@ steps:
           "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."
 
+  # ── Requirements Workflow ──────────────────────────────────────────
+
+  - id: discover_requirements
+    name: "Discover Requirements Context"
+    description: "Scan the project for existing requirements, determine the requirements directory path, and identify the user's intent (create, amend, or reorganize)."
+    instructions_file: steps/discover_requirements.md
+    inputs:
+      - name: goal
+        description: "What the user wants to accomplish — new requirement, amendment, or reorganization"
+    outputs:
+      .deepwork/tmp/requirements_context.md:
+        type: file
+        description: "Requirements directory path, existing requirements index, next available ID, and user intent"
+        required: true
+    dependencies: []
+    reviews:
+      - run_each: .deepwork/tmp/requirements_context.md
+        quality_criteria:
+          "Directory Identified": "The requirements directory path is explicitly stated (default ./requirements/ or custom from AGENTS.md)."
+          "Existing Requirements Listed": "All existing REQ-*.md files are inventoried with their IDs and titles."
+          "Intent Clear": "The user's intent (create, amend, or reorganize) is identified with target requirement IDs."
+
+  - id: draft_requirements
+    name: "Draft Requirements"
+    description: "Create or amend RFC 2119 requirement files and update the REQUIREMENTS.md index."
+    instructions_file: steps/draft_requirements.md
+    inputs:
+      - file: .deepwork/tmp/requirements_context.md
+        from_step: discover_requirements
+    outputs:
+      .deepwork/tmp/requirements_draft.md:
+        type: file
+        description: "List of files created or modified, index update status, and summary of changes"
+        required: true
+    dependencies:
+      - discover_requirements
+    reviews:
+      - run_each: .deepwork/tmp/requirements_draft.md
+        quality_criteria:
+          "RFC 2119 Format": "Every requirement file follows the REQ-NNN format with RFC 2119 keyword declaration and numbered sub-requirements."
+          "Keywords Present": "Every sub-requirement contains at least one RFC 2119 keyword (MUST, SHOULD, MAY, etc.) in uppercase."
+          "Index Updated": "REQUIREMENTS.md index includes all requirement files with correct IDs, titles, and links."
+          "Testable Requirements": "Each sub-requirement describes a verifiable behavior that can be validated by a test or review rule."
+
+  - id: validate_requirements
+    name: "Validate Requirements"
+    description: "Check format consistency, numbering, index completeness, and AGENTS.md documentation for the requirements directory."
+    instructions_file: steps/validate_requirements.md
+    inputs:
+      - file: .deepwork/tmp/requirements_context.md
+        from_step: discover_requirements
+      - file: .deepwork/tmp/requirements_draft.md
+        from_step: draft_requirements
+    outputs:
+      .deepwork/tmp/requirements_validation.md:
+        type: file
+        description: "Validation results for all requirement files, index status, and overall pass/fail"
+        required: true
+    dependencies:
+      - discover_requirements
+      - draft_requirements
+    reviews:
+      - run_each: .deepwork/tmp/requirements_validation.md
+        quality_criteria:
+          "All Files Checked": "Every REQ-*.md file in the requirements directory was validated."
+          "Format Compliance": "All files pass header, numbering, and keyword checks."
+          "Index Complete": "The REQUIREMENTS.md index has no missing or orphaned entries."
+          "Overall Status Clear": "The report states an unambiguous PASS or FAIL with details for any failures."
+
   # ── Doctor Workflow ────────────────────────────────────────────────
 
   - id: check_agent_md

library/jobs/engineer/requirements.md

@@ -1,8 +1,8 @@
 # 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.
+`implement`, `doctor`, and `requirements` 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
@@ -21,8 +21,10 @@ overarching user story and functional RFC 2119 requirements.
 An engineer MUST translate this Product Issue into a distinct Engineering Issue.
 
 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.
+implementation plan, applicable design artifacts (e.g., architecture diagrams,
+data models, schematics, or domain-equivalent artifacts as defined in
+`common_job_info`), and explicit definitions of expected red and green test
+states.
 
 ## 2. Version control initialization
 
@@ -57,12 +59,10 @@ finished and pushed to the remote branch.
 
 ## 5. Artifact generation and continuous integration
 
-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. If the CI system does not produce the expected artifacts, the
-engineer MUST document the gap and manually capture equivalents.
+The engineer MUST verify that the CI system produces visual artifacts appropriate
+to the domain (as listed in `common_job_info`) upon a successful green state. 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
 
@@ -82,22 +82,76 @@ 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.
+explicit links using the PR's permanent numeric URL (e.g.,
+`https://github.com/org/repo/pull/123`) 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
-agent.md file (or equivalent domain documentation).
+AGENTS.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
+AGENTS.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.
+
+## Requirements workflow requirements
+
+## 9. Requirements directory and discovery
+
+Every project using the requirements workflow MUST store requirement files in a
+dedicated directory. The default path SHALL be `./requirements/` relative to the
+repository root.
+
+If a project uses a non-default path, the path MUST be documented in the
+project's agent context file (`AGENTS.md` or equivalent) under a
+`## Requirements` section so that DeepWork can locate it without conflict.
+
+The workflow MUST scan existing `REQ-*.md` files and the `REQUIREMENTS.md` index
+before creating or modifying any requirement.
+
+## 10. Requirement file format
+
+Each requirement file MUST be named `REQ-NNN-slug.md` where `NNN` is a
+zero-padded sequential number and `slug` is a lowercase hyphenated summary.
+
+Each file MUST begin with a heading `# REQ-NNN: Title` followed by a brief
+description and the RFC 2119 key words declaration paragraph.
+
+Sub-requirements MUST be numbered `REQ-NNN.X` starting at 1 and MUST each
+contain at least one RFC 2119 keyword (`MUST`, `MUST NOT`, `SHALL`,
+`SHALL NOT`, `SHOULD`, `SHOULD NOT`, `MAY`, `REQUIRED`, `OPTIONAL`) in
+uppercase.
+
+Every sub-requirement MUST describe a verifiable behavior that can be validated
+by an automated test or a DeepWork review rule.
+
+## 11. Requirements index
+
+A `REQUIREMENTS.md` file MUST exist in the requirements directory and serve as
+the index of all requirement files.
+
+The index MUST be a Markdown table with columns `ID`, `Title`, and `File`
+linking to each `REQ-*.md` file.
+
+Every `REQ-*.md` file in the directory MUST have a corresponding row in the
+index. The index MUST NOT reference files that do not exist.
+
+## 12. Amending requirements
+
+When amending an existing requirement, the engineer MUST preserve existing
+sub-requirement numbers. New sub-requirements SHALL be appended to the end of
+the existing list rather than renumbered, unless the user explicitly requests
+renumbering.
+
+Amendments MUST NOT silently remove or weaken existing sub-requirements. Any
+removal or weakening of a requirement MUST be explicitly noted in the commit
+message.

library/jobs/engineer/steps/discover_requirements.md

@@ -0,0 +1,32 @@
+# Discover requirements context
+
+Read the project's agent context file (`AGENTS.md`, `CLAUDE.md`, or equivalent) to
+determine the requirements directory. Default to `./requirements/` if no override
+is specified.
+
+## Procedure
+
+1. Read the project's agent context file. Look for a `## Requirements` section or
+   any mention of a requirements directory path. If no agent context file exists
+   (`AGENTS.md`, `CLAUDE.md`, or equivalent), treat this as equivalent to no
+   override being specified and default to `./requirements/`.
+2. If a custom path is declared, use it. Otherwise use `./requirements/`.
+3. Check whether the requirements directory exists. If it does, read
+   `REQUIREMENTS.md` (the index) and list all existing `REQ-*.md` files.
+4. Read the user's goal (provided as input). Determine whether they want to:
+   - Create a new requirement from scratch
+   - Amend an existing requirement
+   - Reorganize or renumber requirements
+5. If creating a new requirement, determine the next available `REQ-NNN` number
+   from the existing index.
+
+## Output
+
+Write `.deepwork/tmp/requirements_context.md` containing:
+
+- **Requirements directory**: absolute or relative path
+- **Existing requirements**: table of `ID | Title | File` (empty if none)
+- **Next available ID**: e.g., `REQ-012`
+- **User intent**: one of `create` | `amend` | `reorganize`
+- **Target requirements**: which requirement IDs will be created or modified (for create: the next available ID; for amend/reorganize: the existing IDs)
+- **Custom path override**: whether AGENTS.md declares a non-default path

library/jobs/engineer/steps/draft_requirements.md

@@ -0,0 +1,55 @@
+# Draft requirements
+
+Create or amend RFC 2119 requirement files in the project's requirements directory.
+
+## Format
+
+Each requirement file MUST follow this structure:
+
+```markdown
+# REQ-NNN: Title
+
+Brief description of what this requirement covers.
+
+Key words: RFC 2119 (MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT,
+MAY, REQUIRED, OPTIONAL).
+
+## Requirements
+
+**REQ-NNN.1** The system MUST ...
+
+**REQ-NNN.2** The system SHOULD ...
+```
+
+Rules:
+- File name: `REQ-NNN-slug.md` where slug is a lowercase hyphenated summary.
+- Each sub-requirement is numbered `REQ-NNN.X` starting at 1.
+- Every sub-requirement MUST contain at least one RFC 2119 keyword in uppercase.
+- Requirements MUST be testable — each statement should be verifiable by an
+  automated test or a DeepWork review rule.
+
+## Procedure
+
+1. Read `.deepwork/tmp/requirements_context.md` for directory path, existing
+   requirements, and user intent.
+2. If **creating**: write new `REQ-NNN-slug.md` file(s) in the requirements directory.
+3. If **amending**: read the existing requirement file, apply changes, preserve
+   numbering continuity. Append new sub-requirements rather than renumbering unless
+   the user explicitly requests renumbering.
+4. Update `REQUIREMENTS.md` index to include any new entries. The index MUST be a
+   Markdown table with columns `ID | Title | File`.
+5. If the requirements directory does not exist, create it along with the
+   `REQUIREMENTS.md` index file.
+6. If AGENTS.md does not document the requirements path and the path is non-default
+   (i.e., not `./requirements/` relative to the repository root), add a
+   `## Requirements` section to AGENTS.md declaring the path.
+
+## Output
+
+Write `.deepwork/tmp/requirements_draft.md` containing:
+
+- **Files created**: list of new files written
+- **Files modified**: list of existing files amended
+- **Index updated**: whether REQUIREMENTS.md was created or updated
+- **AGENTS.md updated**: whether AGENTS.md was modified (and why)
+- **Summary of changes**: brief description of each requirement added or modified