Add engineering-workflow: domain-agnostic incremental development pipeline#116
Conversation
Add a complete incremental development workflow that propagates changes through requirements, specifications, and implementation with adversarial audits and human-in-the-loop review at each transition. New components (8): - formats/structured-patch — traceable diff/patch output format - protocols/reasoning/change-propagation — 5-phase change propagation - templates/dev-workflow — interactive orchestration entry point - templates/collaborate-requirements-change — requirements discovery - templates/generate-spec-changes — requirements to design/validation - templates/generate-implementation-changes — specs to implementation - templates/audit-spec-alignment — adversarial spec audit (D1-D7) - templates/audit-implementation-alignment — adversarial impl audit (D8-D13) Key design decisions: - Domain-agnostic: configurable personas let users apply the workflow to software, hardware, mechanical, RF, or protocol engineering - Two audit cycles: spec audit (D1-D7) and implementation audit (D8-D13) using the existing specification-drift taxonomy - Loop-back capability: audit verdicts (PASS/REVISE/RESTART) drive iteration between phases - Standalone phase templates: each phase can be used independently Pipeline: dev-workflow (5 stages with structured-patch artifact flow) Closes microsoft#115 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The workflow is domain-agnostic and applies to all engineering disciplines, not just software development. Rename to reflect this. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a new domain-agnostic incremental development workflow to PromptKit, introducing a structured patch artifact type plus templates/protocols to propagate changes from requirements → specs → implementation with adversarial audits.
Changes:
- Added
structured-patchformat andchange-propagationreasoning protocol to support traceable, layered change propagation. - Added a
dev-workflowinteractive entry template plus standalone phase templates for requirements discovery, spec/impl change generation, and alignment audits. - Registered new components and a
dev-workflowpipeline inmanifest.yaml.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| templates/generate-spec-changes.md | New template to propagate requirement patches into design + validation patches using structured traceability. |
| templates/generate-implementation-changes.md | New template to propagate spec patches into implementation + verification changes with operational constraints. |
| templates/dev-workflow.md | New interactive orchestration template describing the full multi-phase workflow and loop-backs. |
| templates/collaborate-requirements-change.md | New interactive template for requirements discovery and emitting a structured requirements patch. |
| templates/audit-spec-alignment.md | New adversarial audit template for intent → requirements/spec alignment using D1–D7 taxonomy. |
| templates/audit-implementation-alignment.md | New adversarial audit template for spec → implementation/verification alignment using D8–D13 taxonomy. |
| protocols/reasoning/change-propagation.md | New reasoning protocol defining ordered phases for impact analysis, derivation, invariants, completeness, conflicts. |
| formats/structured-patch.md | New output format specifying a structured, traceable patch document with manifest + traceability matrix. |
| manifest.yaml | Registers the new protocol/format/templates and defines a dev-workflow pipeline. |
- Add mandatory section rule to structured-patch format (all 6 sections required even if empty, state 'None identified') - Add No-Impact status to traceability matrix (aligns with change-propagation protocol's completeness check) - Fix [ASSUMED] → [ASSUMPTION] to match anti-hallucination protocol - Fix [UNKNOWN] → [UNKNOWN: <what is missing>] for specificity - Move Pre-Patch Analysis inside Change Context section to comply with structured-patch format's fixed section ordering Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Clarify engineering-workflow output_contract to describe multiple artifacts across phases (patches + audit reports) - Remove consumes from post-audit pipeline stages that don't consume the immediately previous stage's output type - Audit templates now explicitly follow investigation-report format's required 9-section structure with verdict in Open Questions section - (PR description updated separately to reflect engineering-workflow name) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Alan-Jowett
changed the title
- Introduce distinct artifact types (requirements-patch, spec-patch, implementation-patch) in pipeline stages and template contracts for unambiguous artifact handoff - Switch engineering-workflow format to multi-artifact since it produces multiple artifact types across phases (patches + audit reports) - Update output_contract to artifact-set type - Fix protocol ordering in manifest for generate-implementation-changes to match frontmatter (operational-constraints before change-propagation) - Update input_contracts on audit templates to declare multi-type inputs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
| ## Instructions | ||
|
|
||
| Apply the **change-propagation protocol** in order: | ||
|
|
||
| ### Step 1 — Impact Analysis | ||
|
|
||
| For each specification change in the input patch: | ||
|
|
||
| 1. Identify which implementation artifacts are **directly affected** | ||
| (files, modules, components, schematic sheets that implement the | ||
| changed design section). | ||
| 2. Identify which verification artifacts are **directly affected** | ||
| (test files, simulation configs, inspection checklists linked to | ||
| the changed validation entries). | ||
| 3. Identify **indirect impacts** — artifacts that depend on interfaces, | ||
| data structures, or behaviors affected by the specification change. | ||
| 4. Apply the **operational-constraints protocol** — focus on the | ||
| behavioral surface first (APIs, entry points, interfaces), then | ||
| trace inward only as needed for verification. | ||
|
|
There was a problem hiding this comment.
These step-by-step instructions say to apply the change-propagation protocol, but they don’t explicitly include the protocol’s invariant/completeness/conflict phases. Because the template provides its own numbered steps, it’s easy for an agent to follow only Steps 1–4 and miss required checks. Please add explicit steps for invariant checking, completeness verification, and conflict detection (or explicitly reference the protocol phases that must be executed).
| spec_patch: "The structured specification patch (design + validation changes)" | ||
| existing_artifacts: "Existing requirements, design, and validation documents for context" | ||
| input_contract: | ||
| type: [requirements-patch, spec-patch] |
There was a problem hiding this comment.
input_contract.type is documented as a single string label used for chaining (output_contract.type ↔ input_contract.type). Using a YAML list here (type: [requirements-patch, spec-patch]) diverges from that contract model and may confuse tooling/users. Consider choosing a primary contract type (e.g., spec-patch) and listing additional required artifacts in the description/params, similar to other multi-input templates.
| type: [requirements-patch, spec-patch] | |
| type: spec-patch |
| ```markdown | ||
| | Change ID | Type | Target Artifact | Section / Location | Summary | | ||
| |------------|--------|-----------------|--------------------|---------------------| | ||
| | CHG-001 | Add | design-doc | §3.2 API Layer | New endpoint for... | | ||
| | CHG-002 | Modify | validation-plan | TC-012 | Update expected... | | ||
| | CHG-003 | Remove | design-doc | §4.1 Legacy API | Remove deprecated...| | ||
| ``` |
There was a problem hiding this comment.
The example markdown tables use a double leading pipe (||) in each row. Standard Markdown tables use a single | delimiter; the extra | can lead to malformed rendering and may cause agents to reproduce the invalid structure. Please update the examples to standard |-delimited table rows.
| ```markdown | ||
| | Upstream Ref | Downstream Changes | Status | | ||
| |-------------------|-----------------------------|-----------| | ||
| | REQ-FUNC-005 | CHG-001, CHG-002 | Complete | | ||
| | REQ-PERF-002 | CHG-003 | Complete | | ||
| | USER-REQUEST: ... | CHG-004 | Partial | | ||
| ``` |
There was a problem hiding this comment.
The traceability matrix example table also uses || at the start of each row, which is nonstandard Markdown table syntax and may be reproduced incorrectly in generated outputs. Please switch the example to a standard single-| table format.
| name: engineering-workflow | ||
| mode: interactive | ||
| description: > | ||
| Full incremental development workflow with human-in-the-loop review. | ||
| Guides an agent through requirements discovery, specification changes, | ||
| implementation changes, adversarial audits, and deliverable creation. | ||
| Domain-agnostic — works for software, hardware, protocol, or any | ||
| engineering domain. Users select their domain by choosing a persona. |
There was a problem hiding this comment.
The PR description and component list refer to an entry point templates/dev-workflow.md / dev-workflow, but this PR adds templates/engineering-workflow.md with name: engineering-workflow. Please align naming (either rename the template/manifest category or update the PR description/docs) so users can find the correct entry point.
| taxonomies: | ||
| - specification-drift | ||
| format: multi-artifact | ||
| params: | ||
| persona: "Persona to use — select from library (e.g., software-architect, electrical-engineer, mechanical-engineer)" | ||
| project_name: "Name of the project, product, or system being changed" | ||
| change_description: "Natural language description of the desired change" | ||
| existing_artifacts: "Existing requirements, design, validation, implementation, and verification artifacts" | ||
| context: "Additional context — architecture, constraints, domain conventions, toolchain" | ||
| input_contract: null |
There was a problem hiding this comment.
format: multi-artifact conflicts with the workflow’s Phase 1 behavior: the multi-artifact format requires the output to begin with a Deliverables manifest, but Phase 1 expects the assistant to start with interactive discovery questions. Consider either (a) emitting an initial Deliverables manifest (with TBD placeholders) before asking Phase 1 questions, or (b) using a format that doesn’t mandate a manifest at the very start of the session.
| ## Instructions | ||
|
|
||
| Apply the **change-propagation protocol** in order: | ||
|
|
||
| ### Step 1 — Impact Analysis | ||
|
|
||
| For each requirement change in the input patch: | ||
|
|
||
| 1. Identify which design document sections are **directly affected** | ||
| (sections that reference or implement the changed requirement). | ||
| 2. Identify which validation plan entries are **directly affected** | ||
| (test cases linked to the changed requirement). | ||
| 3. Identify **indirect impacts** — sections that depend on assumptions | ||
| or constraints affected by the requirement change. | ||
| 4. For sections verified as unaffected, state WHY. | ||
|
|
There was a problem hiding this comment.
These step-by-step instructions say to apply the change-propagation protocol, but they omit explicit coverage of protocol Phases 3–5 (invariant check, completeness check, conflict detection). Since the template’s steps are likely to be followed verbatim, please add explicit steps for these phases (or clearly state they must be performed in addition to Steps 1–4) to avoid incomplete propagation.
|
@copilot apply changes based on the comments in this thread |
Summary
Adds a complete domain-agnostic incremental development workflow that guides users from intent through implementation with adversarial audits and human-in-the-loop review at every transition.
Closes #115
User Workflow
Phase 1: Requirements Discovery (interactive) Phase 2: Specification Changes (req + design + validation diffs) Phase 3: Specification Audit (adversarial, D1-D7) Phase 4: User Review (loop back on feedback) Phase 5: Implementation Changes (impl + verification diffs) Phase 6: Implementation Audit (adversarial, D8-D13) Phase 7: User Review (loop back on feedback) Phase 8: Create Deliverable (PR, patch set, design package)Entry point:
read and execute templates/dev-workflow.mdNew Components (8)
structured-patchchange-propagationdev-workflowcollaborate-requirements-changegenerate-spec-changesgenerate-implementation-changesaudit-spec-alignmentaudit-implementation-alignmentPlus
dev-workflowpipeline definition in manifest.yaml.Key Design Decisions
Validation
Both validators pass cleanly.