From 94d868317e26cb25c19f16688d636393c6bd2b45 Mon Sep 17 00:00:00 2001 From: Nicholas Romero Date: Mon, 30 Mar 2026 13:50:19 -0500 Subject: [PATCH 1/2] feat(engineer): add requirements workflow for RFC 2119 requirement management Adds a 3-step `requirements` workflow to the engineer library job that creates, amends, and validates RFC 2119 requirement files in a project's `./requirements/` directory (with configurable path via AGENTS.md). Co-Authored-By: Claude Opus 4.6 (1M context) --- library/jobs/engineer/AGENTS.md | 21 +++++ library/jobs/engineer/job.yml | 78 ++++++++++++++++++- library/jobs/engineer/requirements.md | 53 +++++++++++++ .../engineer/steps/discover_requirements.md | 30 +++++++ .../jobs/engineer/steps/draft_requirements.md | 54 +++++++++++++ .../engineer/steps/validate_requirements.md | 34 ++++++++ 6 files changed, 269 insertions(+), 1 deletion(-) create mode 100644 library/jobs/engineer/steps/discover_requirements.md create mode 100644 library/jobs/engineer/steps/draft_requirements.md create mode 100644 library/jobs/engineer/steps/validate_requirements.md diff --git a/library/jobs/engineer/AGENTS.md b/library/jobs/engineer/AGENTS.md index c8de832c..a1ac832d 100644 --- a/library/jobs/engineer/AGENTS.md +++ b/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,8 +31,26 @@ engineer/ ## Workflows - **implement**: 6-step workflow executing engineering work from product issue through PR merge and product sync +- **requirements**: 3-step workflow to create or amend RFC 2119 requirements in the project's requirements directory - **doctor**: 3-step workflow validating agent.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 diff --git a/library/jobs/engineer/job.yml b/library/jobs/engineer/job.yml index 49450519..87ae756c 100644 --- a/library/jobs/engineer/job.yml +++ b/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 diff --git a/library/jobs/engineer/requirements.md b/library/jobs/engineer/requirements.md index 46494465..630909ab 100644 --- a/library/jobs/engineer/requirements.md +++ b/library/jobs/engineer/requirements.md @@ -86,6 +86,59 @@ 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. +## 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. + ## Doctor workflow requirements ## 8. Contextual awareness and the doctor workflow diff --git a/library/jobs/engineer/steps/discover_requirements.md b/library/jobs/engineer/steps/discover_requirements.md new file mode 100644 index 00000000..4e08dee6 --- /dev/null +++ b/library/jobs/engineer/steps/discover_requirements.md @@ -0,0 +1,30 @@ +# 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. +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**: create, amend, or reorganize +- **Target requirements**: which requirement IDs will be created or modified +- **Custom path override**: whether AGENTS.md declares a non-default path diff --git a/library/jobs/engineer/steps/draft_requirements.md b/library/jobs/engineer/steps/draft_requirements.md new file mode 100644 index 00000000..ab4f8c9a --- /dev/null +++ b/library/jobs/engineer/steps/draft_requirements.md @@ -0,0 +1,54 @@ +# 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, + 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 diff --git a/library/jobs/engineer/steps/validate_requirements.md b/library/jobs/engineer/steps/validate_requirements.md new file mode 100644 index 00000000..ee8d3e46 --- /dev/null +++ b/library/jobs/engineer/steps/validate_requirements.md @@ -0,0 +1,34 @@ +# Validate requirements + +Check that all requirement files follow the RFC 2119 format, numbering is +consistent, and the index is complete. + +## Procedure + +1. Read `.deepwork/tmp/requirements_context.md` for the requirements directory path. +2. Read `.deepwork/tmp/requirements_draft.md` for the list of created/modified files. +3. For each `REQ-*.md` file in the requirements directory, verify: + - **Header format**: starts with `# REQ-NNN: Title`. + - **RFC 2119 declaration**: contains the key words declaration paragraph. + - **Sub-requirement format**: each requirement is `**REQ-NNN.X**` with + sequential numbering starting at 1. + - **Keyword presence**: every sub-requirement contains at least one RFC 2119 + keyword (`MUST`, `MUST NOT`, `SHALL`, `SHALL NOT`, `SHOULD`, `SHOULD NOT`, + `MAY`, `REQUIRED`, `OPTIONAL`) in uppercase. + - **Testability**: each sub-requirement describes a verifiable behavior. +4. Verify `REQUIREMENTS.md` index: + - Every `REQ-*.md` file in the directory has a corresponding row. + - No index rows point to missing files. + - IDs are sequential with no gaps (warn on gaps but do not fail). +5. Verify AGENTS.md documents the requirements path if it differs from + `./requirements/`. + +## Output + +Write `.deepwork/tmp/requirements_validation.md` containing: + +- **Files checked**: count of requirement files validated +- **Validation results**: table of `File | Status | Issues` for each file +- **Index status**: PASS or FAIL with details +- **AGENTS.md status**: PASS, FAIL, or N/A (default path needs no documentation) +- **Overall status**: PASS if all checks pass, FAIL if any critical issue found From b7462192af3ab81b0a715a24e0f0a378bd5c222f Mon Sep 17 00:00:00 2001 From: Nicholas Romero Date: Mon, 30 Mar 2026 14:33:23 -0500 Subject: [PATCH 2/2] fix(engineer): address review findings in requirements workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix section ordering in requirements.md (8 before 9-12) - Replace domain-specific language with domain-agnostic references - Fix agent.md → AGENTS.md throughout requirements.md - Add fallback for absent context file in discover_requirements - Add explicit default path reference in draft_requirements step 6 - Define testability criterion and FAIL criteria in validate_requirements - Add engineer job to library/jobs/README.md - Document library job traceability exemption in AGENTS.md Co-Authored-By: Claude Sonnet 4.6 --- library/jobs/README.md | 7 +++ library/jobs/engineer/AGENTS.md | 9 +-- library/jobs/engineer/requirements.md | 59 ++++++++++--------- .../engineer/steps/discover_requirements.md | 8 ++- .../jobs/engineer/steps/draft_requirements.md | 5 +- .../engineer/steps/validate_requirements.md | 15 ++++- 6 files changed, 62 insertions(+), 41 deletions(-) diff --git a/library/jobs/README.md b/library/jobs/README.md index 489aff04..7981a33c 100644 --- a/library/jobs/README.md +++ b/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 diff --git a/library/jobs/engineer/AGENTS.md b/library/jobs/engineer/AGENTS.md index a1ac832d..69cf700f 100644 --- a/library/jobs/engineer/AGENTS.md +++ b/library/jobs/engineer/AGENTS.md @@ -32,7 +32,7 @@ engineer/ - **implement**: 6-step workflow executing engineering work from product issue through PR merge and product sync - **requirements**: 3-step workflow to create or amend RFC 2119 requirements in the project's requirements directory -- **doctor**: 3-step workflow validating agent.md and domain context files +- **doctor**: 3-step workflow validating AGENTS.md and domain context files ## Requirements directory @@ -56,9 +56,10 @@ falls back to `./requirements/`. 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 diff --git a/library/jobs/engineer/requirements.md b/library/jobs/engineer/requirements.md index 630909ab..3e2b5136 100644 --- a/library/jobs/engineer/requirements.md +++ b/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,9 +82,26 @@ 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 +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 +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 @@ -138,19 +155,3 @@ 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. - -## 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). - -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/library/jobs/engineer/steps/discover_requirements.md b/library/jobs/engineer/steps/discover_requirements.md index 4e08dee6..d7e971b7 100644 --- a/library/jobs/engineer/steps/discover_requirements.md +++ b/library/jobs/engineer/steps/discover_requirements.md @@ -7,7 +7,9 @@ is specified. ## Procedure 1. Read the project's agent context file. Look for a `## Requirements` section or - any mention of a requirements directory path. + 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. @@ -25,6 +27,6 @@ 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**: create, amend, or reorganize -- **Target requirements**: which requirement IDs will be created or modified +- **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 diff --git a/library/jobs/engineer/steps/draft_requirements.md b/library/jobs/engineer/steps/draft_requirements.md index ab4f8c9a..d0b9f80b 100644 --- a/library/jobs/engineer/steps/draft_requirements.md +++ b/library/jobs/engineer/steps/draft_requirements.md @@ -40,8 +40,9 @@ Rules: 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, - add a `## Requirements` section to AGENTS.md declaring the path. +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 diff --git a/library/jobs/engineer/steps/validate_requirements.md b/library/jobs/engineer/steps/validate_requirements.md index ee8d3e46..6f7cba7d 100644 --- a/library/jobs/engineer/steps/validate_requirements.md +++ b/library/jobs/engineer/steps/validate_requirements.md @@ -9,13 +9,18 @@ consistent, and the index is complete. 2. Read `.deepwork/tmp/requirements_draft.md` for the list of created/modified files. 3. For each `REQ-*.md` file in the requirements directory, verify: - **Header format**: starts with `# REQ-NNN: Title`. - - **RFC 2119 declaration**: contains the key words declaration paragraph. + - **RFC 2119 declaration**: contains the key words declaration paragraph. The + expected text starts with: `Key words: RFC 2119 (MUST, MUST NOT, SHALL, ...`. - **Sub-requirement format**: each requirement is `**REQ-NNN.X**` with sequential numbering starting at 1. - **Keyword presence**: every sub-requirement contains at least one RFC 2119 keyword (`MUST`, `MUST NOT`, `SHALL`, `SHALL NOT`, `SHOULD`, `SHOULD NOT`, `MAY`, `REQUIRED`, `OPTIONAL`) in uppercase. - - **Testability**: each sub-requirement describes a verifiable behavior. + - **Testability**: each sub-requirement specifies an observable outcome — a + measurable state, detectable artifact, or pass/fail condition. Example of + testable: "The system MUST respond within 200ms." Example of non-testable: + "The system SHOULD be fast." If a file cannot be read or is empty, record + its status as FAIL with issue "File unreadable or empty." 4. Verify `REQUIREMENTS.md` index: - Every `REQ-*.md` file in the directory has a corresponding row. - No index rows point to missing files. @@ -31,4 +36,8 @@ Write `.deepwork/tmp/requirements_validation.md` containing: - **Validation results**: table of `File | Status | Issues` for each file - **Index status**: PASS or FAIL with details - **AGENTS.md status**: PASS, FAIL, or N/A (default path needs no documentation) -- **Overall status**: PASS if all checks pass, FAIL if any critical issue found +- **Overall status**: PASS if all checks pass. FAIL if any of the following: bad + header format, missing RFC 2119 declaration, missing keyword in any + sub-requirement, broken index rows (row points to missing file), or + unreadable/empty requirement files. ID gaps and missing AGENTS.md entry + (when using the default path) are warnings only and do not cause FAIL.