mirror of
https://github.com/alexhopeoconnor/firmware.git
synced 2026-10-19 18:01:30 +10:00
Implement Hardware Support Agent Specification and Workflow
This commit is contained in:
Ben Meadors
@@ -0,0 +1,35 @@
|
||||
# Specification Quality Checklist: Hardware Support Agent
|
||||
|
||||
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
||||
**Created**: 2026-03-25
|
||||
**Feature**: [spec.md](/Users/benmeadors/Documents/GitHub/firmware/specs/129-hardware-support-agent/spec.md)
|
||||
|
||||
## Content Quality
|
||||
|
||||
- [x] No implementation details (languages, frameworks, APIs)
|
||||
- [x] Focused on user value and business needs
|
||||
- [x] Written for non-technical stakeholders
|
||||
- [x] All mandatory sections completed
|
||||
|
||||
## Requirement Completeness
|
||||
|
||||
- [x] No [NEEDS CLARIFICATION] markers remain
|
||||
- [x] Requirements are testable and unambiguous
|
||||
- [x] Success criteria are measurable
|
||||
- [x] Success criteria are technology-agnostic (no implementation details)
|
||||
- [x] All acceptance scenarios are defined
|
||||
- [x] Edge cases are identified
|
||||
- [x] Scope is clearly bounded
|
||||
- [x] Dependencies and assumptions identified
|
||||
|
||||
## Feature Readiness
|
||||
|
||||
- [x] All functional requirements have clear acceptance criteria
|
||||
- [x] User scenarios cover primary flows
|
||||
- [x] Feature meets measurable outcomes defined in Success Criteria
|
||||
- [x] No implementation details leak into specification
|
||||
|
||||
## Notes
|
||||
|
||||
- Specification validated against the repository constitution on 2026-03-25.
|
||||
- Initial scope is intentionally bounded to reusable hardware context plus safe board-intake and scaffolding workflow preparation.
|
||||
@@ -0,0 +1,58 @@
|
||||
# Contract: Board Intake Request And Assessment
|
||||
|
||||
## Purpose
|
||||
|
||||
This contract defines the minimum maintainer input and the expected workflow output for the hardware-support-agent feature.
|
||||
|
||||
## Input Contract
|
||||
|
||||
### Required Fields
|
||||
|
||||
- `environment_name`: Proposed PlatformIO environment name for the new board.
|
||||
- `hardware_model`: Meshtastic hardware model identifier to assign.
|
||||
- `display_name`: Human-readable board name.
|
||||
- `architecture`: Target architecture family such as `esp32`, `esp32-s3`, `nrf52840`, `rp2040`, or `stm32`.
|
||||
|
||||
### Recommended Fields
|
||||
|
||||
- `hardware_model_slug`: Repository-style uppercase slug if already known.
|
||||
- `actively_supported`: Whether the board is intended to be actively supported.
|
||||
- `support_level`: Intended `custom_meshtastic_support_level` value.
|
||||
- `source_materials`: Links, file paths, or notes for schematics, pinouts, datasheets, or vendor pages.
|
||||
- `board_notes`: Freeform notes about revisions, peripherals, or known uncertainty.
|
||||
|
||||
## Validation Rules
|
||||
|
||||
- The workflow must reject or pause on missing required fields.
|
||||
- The workflow must detect conflicts with existing environment names or existing hardware identifiers where discoverable.
|
||||
- The workflow must not invent radio, power, display, GPS, input, or auxiliary pin mappings.
|
||||
- The workflow must identify when architecture defaults may be relevant and flag them for human review.
|
||||
|
||||
## Output Contract
|
||||
|
||||
### Required Assessment Sections
|
||||
|
||||
- `expected_artifacts`: What board-support artifacts are likely required.
|
||||
- `required_metadata`: What `custom_meshtastic_*` metadata and related fields must be decided.
|
||||
- `matched_patterns`: Existing repository examples that are closest to the request.
|
||||
- `evidence_gaps`: Missing or conflicting facts that block safe scaffolding.
|
||||
- `risk_flags`: Conditions that require special maintainer attention.
|
||||
- `next_actions`: Concrete steps to move the request toward scaffold readiness.
|
||||
- `scaffold_ready`: Boolean decision indicating whether draft file generation is safe.
|
||||
|
||||
## Artifact Expectations
|
||||
|
||||
Depending on the board and architecture, the assessment should consider whether the request will need:
|
||||
|
||||
- a new or reused variant directory under `variants/<architecture>/...`
|
||||
- `variant.h`
|
||||
- optional `variant.cpp`
|
||||
- one or more PlatformIO environments with `custom_meshtastic_*` metadata
|
||||
- board images, tags, partition-scheme metadata, or DFU metadata
|
||||
- any architecture-specific board files or notes for inherited defaults
|
||||
|
||||
## Non-Goals For Phase 1
|
||||
|
||||
- Direct parsing of PDF schematics.
|
||||
- Automatic merging of new board files into the repository.
|
||||
- Any change to firmware runtime behavior, protocol behavior, or shared board defaults.
|
||||
@@ -0,0 +1,124 @@
|
||||
# Data Model: Hardware Support Agent
|
||||
|
||||
## Hardware Support Context
|
||||
|
||||
Purpose: Repository-backed summary of current target-definition patterns across supported board variants.
|
||||
|
||||
Fields:
|
||||
|
||||
- source_paths: list of repository glob roots used to build the context
|
||||
- generated_at: timestamp or generation marker
|
||||
- variant_count: integer count of scanned variant directories
|
||||
- environment_count: integer count of summarized PlatformIO environments
|
||||
- metadata*keys: list of observed `custom_meshtastic*\*` keys
|
||||
- category_counts: mapping of capability category to common macros and frequencies
|
||||
- architecture_inventory: list of architecture groups and their environments
|
||||
- representative_examples: list of example boards with extracted metadata and macro samples
|
||||
- cautions: list of caveats about inherited defaults, multi-environment boards, and verification limits
|
||||
|
||||
Validation rules:
|
||||
|
||||
- Must be derived from repository state rather than hand-maintained guesses.
|
||||
- Must clearly separate explicit declarations from inherited/default behavior where known.
|
||||
- Must remain read-only context and not imply that any new board is validated for merge.
|
||||
|
||||
Relationships:
|
||||
|
||||
- Used by Board Intake Request as the canonical repository pattern source.
|
||||
|
||||
## Board Intake Request
|
||||
|
||||
Purpose: Maintainer-supplied description of a proposed new board or board revision.
|
||||
|
||||
Fields:
|
||||
|
||||
- environment_name: proposed PlatformIO environment name
|
||||
- hardware_model: numeric or repository-convention hardware model identifier
|
||||
- hardware_model_slug: uppercase slug when known
|
||||
- display_name: human-readable board name
|
||||
- architecture: target family such as `esp32-s3` or `nrf52840`
|
||||
- source_materials: optional list of schematic, pinout, datasheet, or board-page references
|
||||
- support_level: optional intended support metadata
|
||||
- actively_supported: optional boolean intent
|
||||
- board_notes: optional maintainer notes about revisions, optional peripherals, or known gaps
|
||||
|
||||
Validation rules:
|
||||
|
||||
- `environment_name`, `hardware_model`, and `display_name` are required for phase 1 intake.
|
||||
- Architecture is required before any artifact expectation can be considered complete.
|
||||
- Source materials are optional for submission but required for moving unresolved hardware fields toward scaffold generation.
|
||||
- Conflicts with existing environment names or hardware identifiers must be surfaced.
|
||||
|
||||
Relationships:
|
||||
|
||||
- Produces one Intake Assessment.
|
||||
- May eventually lead to one or more Board Support Scaffolds.
|
||||
|
||||
## Intake Assessment
|
||||
|
||||
Purpose: Structured result of evaluating a Board Intake Request against repository patterns and evidence sufficiency.
|
||||
|
||||
Fields:
|
||||
|
||||
- expected_artifacts: list of files or sections likely needed, such as `variant.h`, optional `variant.cpp`, PlatformIO environment entries, board metadata, images, or tags
|
||||
- required*metadata: list of mandatory `custom_meshtastic*\*` values and board-definition fields
|
||||
- matched_patterns: list of related repository examples by architecture or board family
|
||||
- evidence_gaps: list of unresolved or conflicting hardware facts
|
||||
- risk_flags: list of issues such as ambiguous board revisions, unsupported peripherals, or inherited-default uncertainty
|
||||
- next_actions: ordered maintainer actions needed before safe scaffold generation
|
||||
- scaffold_ready: boolean indicating whether evidence is sufficient for a later scaffold phase
|
||||
|
||||
Validation rules:
|
||||
|
||||
- Must never infer unsupported pin mappings silently.
|
||||
- Must describe missing information in maintainer-actionable language.
|
||||
- Must remain architecture- and variant-scoped.
|
||||
|
||||
Relationships:
|
||||
|
||||
- Derived from Board Intake Request and Hardware Support Context.
|
||||
- Blocks or permits creation of Board Support Scaffold.
|
||||
|
||||
## Evidence Gap
|
||||
|
||||
Purpose: Specific missing, conflicting, or ambiguous fact that prevents safe draft generation.
|
||||
|
||||
Fields:
|
||||
|
||||
- category: metadata, radio, display, input, GPS, power, storage, connectivity, or revision-scope
|
||||
- description: maintainer-readable explanation of what is missing or conflicting
|
||||
- affected_artifact: target file or configuration area impacted
|
||||
- required_evidence: type of source needed to resolve the gap
|
||||
- blocking: boolean indicating whether the gap prevents scaffold generation
|
||||
|
||||
Validation rules:
|
||||
|
||||
- Must be traceable to a missing repository pattern or missing board truth.
|
||||
- Must not be collapsed into generic “needs more info” language when the specific blocker is knowable.
|
||||
|
||||
Relationships:
|
||||
|
||||
- Belongs to an Intake Assessment.
|
||||
|
||||
## Board Support Scaffold
|
||||
|
||||
Purpose: Draft board-support content for a new target once evidence is sufficient.
|
||||
|
||||
Fields:
|
||||
|
||||
- target_variant_dir: proposed variant directory path
|
||||
- variant_h_content: draft content or structured sections for `variant.h`
|
||||
- variant_cpp_content: optional draft for `variant.cpp`
|
||||
- platformio_env_content: draft PlatformIO environment metadata and extends chain
|
||||
- unresolved_annotations: inline markers for any remaining non-blocking maintainer review items
|
||||
- source_basis: references to intake data and repository patterns used to draft content
|
||||
|
||||
Validation rules:
|
||||
|
||||
- Must only include fields backed by evidence and repository conventions.
|
||||
- Must preserve variant-scoped truth and never modify unrelated board definitions.
|
||||
- May only be produced when Intake Assessment marks `scaffold_ready` true.
|
||||
|
||||
Relationships:
|
||||
|
||||
- Produced from Intake Assessment after gaps are resolved.
|
||||
@@ -0,0 +1,97 @@
|
||||
# Implementation Plan: Hardware Support Agent
|
||||
|
||||
**Branch**: `[129-hardware-support-agent]` | **Date**: 2026-03-25 | **Spec**: /Users/benmeadors/Documents/GitHub/firmware/specs/129-hardware-support-agent/spec.md
|
||||
**Input**: Feature specification from `/Users/benmeadors/Documents/GitHub/firmware/specs/129-hardware-support-agent/spec.md`
|
||||
|
||||
**Note**: This plan covers Phase 0 and Phase 1 outputs for a constitution-safe first increment. The first delivery scope centers on repository-backed hardware context plus intake validation and report generation; scaffold generation remains designed but gated behind sufficient evidence.
|
||||
|
||||
## Summary
|
||||
|
||||
Build a Copilot-oriented hardware support workflow for Meshtastic that starts from repository-derived board-definition context, accepts a constrained board intake request, and produces a structured readiness report before any new board files are drafted. The technical approach uses lightweight Python tooling and repository-local markdown/JSON contract artifacts to inventory existing `variant.h` and `platformio.ini` patterns, normalize maintainer inputs, identify evidence gaps, and prepare a later scaffolding phase without changing live firmware behavior.
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Language/Version**: Python 3.x for workflow tooling, Markdown for generated artifacts, existing C/C++/PlatformIO repository conventions for downstream scaffold targets
|
||||
**Primary Dependencies**: Python standard library for inventory/intake tooling, existing Spec Kit artifacts, repository-local Copilot prompt/agent files, PlatformIO environment metadata conventions already in `variants/**/platformio.ini`
|
||||
**Storage**: Repository-local files under `docs/`, `specs/129-hardware-support-agent/`, optional future intake examples under repo docs or fixtures
|
||||
**Testing**: Targeted script execution, generated artifact review, `python3 bin/generate_hardware_support_context.py`, `trunk fmt` where applicable for markdown/templates, and targeted follow-up validation against representative variant files
|
||||
**Target Platform**: Maintainer workflow inside the Meshtastic firmware repository on macOS/Linux development environments; outputs describe supported firmware architectures including ESP32, ESP32-S3, ESP32-C3, ESP32-C6, nRF52, RP2040/RP2350, STM32, and native patterns
|
||||
**Project Type**: Repository tooling and Copilot workflow support
|
||||
**Performance Goals**: Generate context and intake reports quickly enough for interactive maintainer use on a local checkout; avoid repository-wide processing that would materially slow a normal Copilot session
|
||||
**Constraints**: No changes to mesh protocol behavior or shared device defaults; no guessing of pin mappings; architecture-specific truth must stay variant-scoped; keep implementation dependency-light and reviewable
|
||||
**Scale/Scope**: Inventory currently spans 166 variant directories and 212 PlatformIO environments; phase 1 scope covers context generation, intake contract, evidence-gap reporting, and custom-agent planning, not autonomous end-to-end board enablement
|
||||
|
||||
## Constitution Check
|
||||
|
||||
_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._
|
||||
|
||||
- Safety-critical mesh impact: Pass. This feature is workflow/documentation/tooling only and does not modify routing, airtime, MQTT, channel, packet-path, or public default behavior.
|
||||
- Variant and platform scope: Pass. The workflow is explicitly scoped to board-definition artifacts and requires variant-specific evidence before any scaffold output is permitted.
|
||||
- Validation evidence: Pass with explicit plan. Validation for this phase is `python3 bin/generate_hardware_support_context.py`, manual spot-check against representative variants, and review of generated documentation/contracts. Later implementation phases should add targeted intake fixture checks.
|
||||
- Resource, power, memory, dependency impact: Pass. The feature adds lightweight local tooling and markdown contracts only, with no runtime firmware impact and no new external runtime dependency requirement.
|
||||
- Constitutional violations or gaps: No active violations for Phase 0/1 planning. The only open product choice is whether future phase 2 includes scaffold generation immediately or remains report-only until more intake validation exists.
|
||||
|
||||
### Post-Design Re-Check
|
||||
|
||||
- Safety-critical mesh impact remains unchanged after design: no firmware runtime path is altered.
|
||||
- Variant-scoped hardware truth is reinforced by the intake contract and evidence-gap model.
|
||||
- Validation evidence remains sufficient for design artifacts, with implementation tasks needing targeted script-level checks.
|
||||
- Resource and dependency impact remains minimal and repository-local.
|
||||
- No justification entries are required in Complexity Tracking for this plan.
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Documentation (this feature)
|
||||
|
||||
```text
|
||||
specs/129-hardware-support-agent/
|
||||
├── plan.md
|
||||
├── research.md
|
||||
├── data-model.md
|
||||
├── quickstart.md
|
||||
├── contracts/
|
||||
│ └── board-intake-contract.md
|
||||
└── tasks.md
|
||||
```
|
||||
|
||||
### Source Code (repository root)
|
||||
|
||||
```text
|
||||
.github/
|
||||
├── agents/
|
||||
└── prompts/
|
||||
|
||||
bin/
|
||||
├── generate_hardware_support_context.py
|
||||
├── board_intake.py
|
||||
└── board_scaffold.py
|
||||
|
||||
docs/
|
||||
└── hardware-support-context.md
|
||||
|
||||
variants/
|
||||
├── esp32/
|
||||
├── esp32c3/
|
||||
├── esp32c6/
|
||||
├── esp32s2/
|
||||
├── esp32s3/
|
||||
├── native/
|
||||
├── nrf52840/
|
||||
├── rp2040/
|
||||
├── rp2350/
|
||||
└── stm32/
|
||||
```
|
||||
|
||||
**Structure Decision**: Use the existing single-repository tooling structure. Planning artifacts live under `specs/129-hardware-support-agent/`, reusable generated context stays in `docs/`, implementation scripts live in `bin/`, and any future custom Copilot workflow files belong in `.github/prompts/` and `.github/agents/`. No new top-level application structure is needed.
|
||||
|
||||
## Complexity Tracking
|
||||
|
||||
No constitutional violations or complexity exceptions are currently required.
|
||||
|
||||
## Review Notes
|
||||
|
||||
- **SC-004** is a post-launch business metric and is not a blocking acceptance gate before merge. A timed baseline comparison should be collected after the first real board intake using the completed workflow.
|
||||
- Validation completed so far: `python3 bin/generate_hardware_support_context.py --validate`, `python3 bin/board_intake.py bin/fixtures/intake_minimal.json --validate`, `python3 bin/board_intake.py bin/fixtures/intake_full.json`, `python3 bin/board_intake.py bin/fixtures/intake_multi_env.json`, `python3 bin/board_scaffold.py bin/fixtures/intake_full.json`, and `python3 bin/board_scaffold.py bin/fixtures/intake_multi_env.json`.
|
||||
- `bin/board_scaffold.py` intentionally emits placeholder pin and metadata values plus `// TODO: verify — ...` annotations. Generated scaffold output is draft-only and not suitable for direct merge without maintainer review against schematics and existing board patterns.
|
||||
- Scaffold generation currently writes to `generated/hardware-support/` rather than directly into `variants/` to keep the workflow reviewable and constitution-safe.
|
||||
- Skipped validations: no targeted `pio run`, native test, or simulator run was executed because this feature adds repository tooling and generated draft artifacts only; no firmware runtime files under `src/` were changed.
|
||||
@@ -0,0 +1,111 @@
|
||||
# Quickstart: Hardware Support Agent
|
||||
|
||||
## Goal
|
||||
|
||||
Use the repository-backed hardware support workflow to understand current board-definition patterns and evaluate whether a new board request is ready for safe scaffolding.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Work from the repository root.
|
||||
- Ensure Python 3 is available.
|
||||
- Have the new board’s minimum intake information ready:
|
||||
- proposed PlatformIO environment name
|
||||
- hardware model identifier
|
||||
- display name
|
||||
- target architecture
|
||||
- any available schematic, pinout, or datasheet references
|
||||
|
||||
## Step 1: Regenerate the repository context artifact
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
python3 bin/generate_hardware_support_context.py
|
||||
```
|
||||
|
||||
Review:
|
||||
|
||||
- `docs/hardware-support-context.md`
|
||||
|
||||
Confirm that the architectures, representative examples, and metadata keys still reflect the current repository state.
|
||||
|
||||
## Step 2: Prepare the board intake request
|
||||
|
||||
Capture the request using the contract in:
|
||||
|
||||
- `specs/129-hardware-support-agent/contracts/board-intake-contract.md`
|
||||
|
||||
At minimum, fill:
|
||||
|
||||
- environment name
|
||||
- hardware model
|
||||
- display name
|
||||
- architecture
|
||||
|
||||
Add source materials for radio, display, power, GPS, input, and auxiliary peripherals when available.
|
||||
|
||||
## Step 3: Evaluate readiness
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
python3 bin/board_intake.py path/to/intake.json
|
||||
```
|
||||
|
||||
The intake report now includes:
|
||||
|
||||
- request summary
|
||||
- expected artifacts
|
||||
- required metadata
|
||||
- matched repository patterns
|
||||
- blocking and non-blocking evidence gaps
|
||||
- risk flags
|
||||
- next actions
|
||||
- a `scaffold_ready` decision
|
||||
|
||||
For gate-style validation, run:
|
||||
|
||||
```bash
|
||||
python3 bin/board_intake.py path/to/intake.json --validate
|
||||
```
|
||||
|
||||
This exits non-zero when blocking gaps remain.
|
||||
|
||||
## Step 4: Generate scaffold output when ready
|
||||
|
||||
If Step 3 reports `scaffold_ready: true`, run:
|
||||
|
||||
```bash
|
||||
python3 bin/board_scaffold.py path/to/intake.json --output-dir generated/hardware-support
|
||||
```
|
||||
|
||||
Expected outputs:
|
||||
|
||||
- `generated/hardware-support/variants/<arch>/<variant-dir>/variant.h`
|
||||
- `generated/hardware-support/variants/<arch>/<variant-dir>/platformio.ini`
|
||||
- optional `variant.cpp` for ESP32-family targets
|
||||
|
||||
If the intake is not scaffold-ready, the scaffold command prints the assessment and exits non-zero instead of generating files.
|
||||
|
||||
## Step 5: Validate the workflow artifacts
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
python3 bin/generate_hardware_support_context.py
|
||||
python3 bin/board_intake.py bin/fixtures/intake_full.json
|
||||
python3 bin/board_scaffold.py bin/fixtures/intake_full.json --output-dir generated/hardware-support
|
||||
```
|
||||
|
||||
Then manually spot-check representative targets such as:
|
||||
|
||||
- `variants/esp32/tbeam`
|
||||
- `variants/esp32s3/tlora-pager`
|
||||
- `variants/nrf52840/t-echo`
|
||||
- `variants/rp2040/rak11310`
|
||||
|
||||
Ensure the generated context, intake assessment, and scaffold output remain consistent with repository truth.
|
||||
|
||||
## Next Step
|
||||
|
||||
Use [hardware-support.prompt.md](.github/prompts/hardware-support.prompt.md) and [hardware-support.agent.md](.github/agents/hardware-support.agent.md) to invoke the workflow directly from Copilot.
|
||||
@@ -0,0 +1,46 @@
|
||||
# Research: Hardware Support Agent
|
||||
|
||||
## Decision: Use repository-local Python tooling and markdown artifacts as the first implementation slice
|
||||
|
||||
Rationale: The repository already uses lightweight scripts under `bin/` and maintains board truth primarily in `variants/**/platformio.ini` and `variants/**/variant.h`. A Python script plus markdown outputs fits existing repo patterns, keeps dependencies minimal, and provides immediate value without touching firmware runtime code.
|
||||
|
||||
Alternatives considered:
|
||||
|
||||
- Implement the first increment directly as a full custom Copilot agent that generates new board files. Rejected because the workflow still needs a safer evidence-validation layer before scaffolding hardware definitions.
|
||||
- Build a standalone service or extension-backed parser. Rejected because it would add unnecessary complexity, operational overhead, and dependencies for a repo-local maintainer workflow.
|
||||
|
||||
## Decision: Treat intake validation and readiness reporting as the first generation boundary
|
||||
|
||||
Rationale: The constitution requires verified, variant-scoped hardware truth and forbids guessing pins or capabilities. A report-first boundary lets maintainers capture missing evidence, expected artifacts, and metadata requirements before draft files are produced.
|
||||
|
||||
Alternatives considered:
|
||||
|
||||
- Generate `variant.h` and `platformio.ini` scaffolding immediately from minimum inputs. Rejected because environment name, `hw_model`, and display name are not enough to guarantee correct radio, power, display, and peripheral mappings.
|
||||
- Block all workflow progress until every future scaffold field is known. Rejected because maintainers still need a useful way to understand what is missing and what repository patterns apply.
|
||||
|
||||
## Decision: Reuse the existing hardware inventory document as the canonical context input for planning
|
||||
|
||||
Rationale: `docs/hardware-support-context.md` already inventories metadata keys, common macro categories, and representative board examples across the repository. That artifact can serve as the phase 1 foundation for both maintainers and future agent prompts.
|
||||
|
||||
Alternatives considered:
|
||||
|
||||
- Generate a new per-architecture context file for each family. Rejected for now because a single canonical context artifact is easier to review and sufficient for the first intake/report workflow.
|
||||
- Depend on maintainers manually browsing variant files during intake. Rejected because it defeats the feature goal of reducing rediscovery work.
|
||||
|
||||
## Decision: Represent the maintainer workflow as a small set of explicit entities and a human-readable contract
|
||||
|
||||
Rationale: The feature is primarily a repository workflow, not a networked API. A markdown contract describing required fields, validations, and outputs is sufficient for Spec Kit design and future agent/prompt implementation.
|
||||
|
||||
Alternatives considered:
|
||||
|
||||
- Define a JSON Schema or OpenAPI contract immediately. Rejected for phase 1 because no external service boundary exists yet and the workflow is still evolving.
|
||||
- Keep the contract implicit in prompt text only. Rejected because it would be harder to review, test, and keep aligned with the constitution.
|
||||
|
||||
## Decision: Keep scaffold generation as a designed later phase gated by evidence sufficiency
|
||||
|
||||
Rationale: The user wants the end state to include new board-support scaffolding, but constitutional safety requires a stronger intake and validation model first. Planning the later phase now preserves momentum without collapsing safe and unsafe scopes together.
|
||||
|
||||
Alternatives considered:
|
||||
|
||||
- Remove scaffolding from the feature entirely. Rejected because it is core to the requested long-term outcome.
|
||||
- Merge report generation and scaffolding into a single undifferentiated phase. Rejected because it weakens reviewability and blurs the safety boundary.
|
||||
@@ -0,0 +1,170 @@
|
||||
# Feature Specification: Hardware Support Agent
|
||||
|
||||
**Feature Branch**: `[129-hardware-support-agent]`
|
||||
**Created**: 2026-03-25
|
||||
**Status**: Draft
|
||||
**Input**: User description: "Implement the feature specification based on the updated constitution. I want to build an agent inside copilot to add new hardware support, including variant.h/cpp, any platformio ini environments will all of our custom metadata, and all of the pinmappings. I would start this process by just giving the board environment name, hw_model, display name, and perhaps some source materials illustrating the pin mappings in a PDF schematic for instance. I think we should start by creating a context for you in the form of a markdown file documenting all of the current input, button, radio, gpio, and other common pins we use in the meshtastic firmware at a device target definition level, so that we reuse instead of re-invent."
|
||||
|
||||
## User Scenarios & Testing _(mandatory)_
|
||||
|
||||
<!--
|
||||
IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
|
||||
Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
|
||||
you should still have a viable MVP (Minimum Viable Product) that delivers value.
|
||||
|
||||
Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
|
||||
Think of each story as a standalone slice of functionality that can be:
|
||||
- Developed independently
|
||||
- Tested independently
|
||||
- Deployed independently
|
||||
- Demonstrated to users independently
|
||||
-->
|
||||
|
||||
### User Story 1 - Build Reusable Hardware Context (Priority: P1)
|
||||
|
||||
As a firmware maintainer adding support for a new device, I want a single repository-backed reference
|
||||
that summarizes the common board-definition inputs already used across Meshtastic targets so I can
|
||||
start from verified patterns instead of re-deriving pins, feature flags, and board metadata from scratch.
|
||||
|
||||
**Why this priority**: Without an authoritative context source, any later agent workflow will repeat the
|
||||
same manual discovery work and risks copying incorrect or incomplete target definitions.
|
||||
|
||||
**Independent Test**: Can be fully tested by generating the hardware context artifact from the current
|
||||
repository and confirming it captures existing target-definition fields, common pins, and board-scoped
|
||||
capability patterns for a representative set of boards.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** an existing firmware checkout with multiple board variants, **When** a maintainer requests
|
||||
the hardware support context, **Then** the system produces a markdown artifact that documents current
|
||||
board-definition inputs, common pin categories, and recurring variant-level capabilities from the repo.
|
||||
2. **Given** a maintainer reviewing an existing board, **When** they inspect the context artifact,
|
||||
**Then** they can identify the board environment, hardware model identifiers, display-related fields,
|
||||
radio pin definitions, input pins, and other commonly reused target-definition elements without
|
||||
manually scanning many variant files.
|
||||
|
||||
---
|
||||
|
||||
### User Story 2 - Define New Board Intake (Priority: P2)
|
||||
|
||||
As a firmware maintainer, I want to provide a small set of board inputs such as environment name,
|
||||
hardware model, display name, and source materials so the Copilot workflow can determine what new
|
||||
hardware support artifacts need to be created or filled in.
|
||||
|
||||
**Why this priority**: A constrained intake contract is required before the workflow can safely generate
|
||||
variant files and PlatformIO environments for new hardware support.
|
||||
|
||||
**Independent Test**: Can be tested independently by supplying the declared board inputs for a hypothetical
|
||||
new target and confirming the workflow identifies required artifacts, missing evidence, and board-definition
|
||||
fields that must be resolved before code generation proceeds.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a maintainer provides an environment name, hardware model, display name, and source references,
|
||||
**When** the intake workflow runs, **Then** it identifies the expected target-definition artifacts,
|
||||
required metadata fields, and unresolved board details that still need confirmation.
|
||||
2. **Given** the supplied materials do not establish enough hardware truth for safe generation,
|
||||
**When** the workflow evaluates the request, **Then** it explicitly flags the missing pin mappings,
|
||||
peripheral capabilities, or board metadata instead of guessing silently.
|
||||
|
||||
---
|
||||
|
||||
### User Story 3 - Generate Board Support Scaffolding (Priority: P3)
|
||||
|
||||
As a firmware maintainer, I want the Copilot workflow to use the validated intake and reusable context to
|
||||
draft board-support artifacts such as `variant.h`, optional `variant.cpp`, and PlatformIO environment content
|
||||
with repository-specific metadata so I can add new hardware support consistently and with less manual setup.
|
||||
|
||||
**Why this priority**: This delivers the actual acceleration benefit, but it depends on verified context and
|
||||
safe intake rules to avoid generating incorrect hardware support.
|
||||
|
||||
**Independent Test**: Can be tested independently by running the workflow for a new board request and
|
||||
confirming it produces scaffold content or structured instructions that align with repository patterns and
|
||||
does not invent unsupported hardware details.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** validated board inputs and sufficient source evidence, **When** the maintainer requests new
|
||||
hardware support scaffolding, **Then** the workflow drafts the required board-support files and metadata
|
||||
using existing repository conventions.
|
||||
2. **Given** the request would affect hardware flags, pin mappings, or build metadata beyond the available
|
||||
evidence, **When** scaffolding is attempted, **Then** the workflow limits output to supported fields and
|
||||
clearly marks unresolved items for human confirmation.
|
||||
|
||||
---
|
||||
|
||||
### Edge Cases
|
||||
|
||||
- The requested board environment name conflicts with an existing PlatformIO environment or target directory.
|
||||
- The same hardware model appears under multiple existing naming conventions and the correct repository form is ambiguous.
|
||||
- A schematic or PDF source omits some pins or names them differently than the repository’s existing macros.
|
||||
- A target uses architecture defaults today, so the context artifact must distinguish explicitly declared pins from inherited defaults.
|
||||
- A board has multiple display or radio options, optional peripherals, or revision-specific pinouts that cannot be collapsed into one truth.
|
||||
- The request includes peripherals that exist in source material but are not currently supported by repository patterns.
|
||||
- A generated board definition would require changing shared defaults or introducing unverified power, timing, or RF assumptions.
|
||||
|
||||
## Requirements _(mandatory)_
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- **FR-001**: The system MUST produce a repository-local hardware context artifact that documents the current
|
||||
target-definition patterns used for board support in this firmware repository.
|
||||
- **FR-002**: The hardware context artifact MUST describe, at minimum, the board environment name,
|
||||
hardware model identifier, display-related identifiers, radio pin group, input/button-related pins,
|
||||
and other commonly reused pin or capability categories present at the device-target-definition level.
|
||||
- **FR-003**: The hardware context artifact MUST distinguish board-specific declarations from architecture-level
|
||||
defaults or inherited behavior when that distinction affects new board support work.
|
||||
- **FR-004**: Users MUST be able to initiate the workflow by providing a minimal set of board inputs that includes
|
||||
board environment name, hardware model, display name, and target architecture, with optional supporting source materials.
|
||||
Architecture is required because expected artifacts and matched patterns cannot be determined without it.
|
||||
- **FR-005**: The intake workflow MUST identify which board-support artifacts are expected for the request,
|
||||
including variant files and PlatformIO environment content where applicable.
|
||||
- **FR-006**: The intake workflow MUST surface missing or conflicting hardware evidence instead of inventing
|
||||
unresolved pins, capabilities, metadata, or power assumptions.
|
||||
- **FR-007**: The workflow MUST preserve variant-scoped hardware truth by keeping generated or suggested values
|
||||
scoped to the intended target architecture, board, and board revision when known.
|
||||
- **FR-008**: The workflow MUST support repository-specific metadata required for new PlatformIO environments,
|
||||
including custom support metadata already used in this codebase.
|
||||
- **FR-009**: The workflow MUST be able to draft scaffold content for `variant.h`, optional `variant.cpp`, and
|
||||
related target files only when the provided evidence is sufficient to do so safely.
|
||||
- **FR-010**: The workflow MUST record unresolved questions in a form the maintainer can act on before using any
|
||||
scaffolded board support in the repository.
|
||||
- **FR-011**: The workflow MUST be applicable to current Meshtastic hardware target definitions across supported
|
||||
architectures, while allowing architecture-specific details to remain architecture-scoped.
|
||||
- **FR-012**: The workflow MUST not change public protocol behavior, shared radio safety defaults, or unrelated
|
||||
board definitions as part of preparing new hardware support context.
|
||||
|
||||
Where relevant, requirements MUST also state:
|
||||
|
||||
- affected architectures, boards, or modules: ESP32, ESP32-S3, ESP32-C3, nRF52, RP2040/RP2350, STM32WL, and Portduino-style target-definition patterns where present in repo conventions
|
||||
- whether behavior changes public defaults, protocol compatibility, or generated artifacts: this feature must not alter public mesh defaults or protocol compatibility; it may create or update documentation artifacts for board-support workflow context
|
||||
- any required validation evidence for high-risk mesh, hardware, or power behavior: targeted verification of generated context against representative variant files and naming patterns is required before relying on it for scaffolding
|
||||
|
||||
### Key Entities _(include if feature involves data)_
|
||||
|
||||
- **Hardware Support Context**: A repository-backed reference artifact that summarizes the current board-support
|
||||
fields, common pin categories, variant capability macros, and target-definition conventions used across the firmware.
|
||||
- **Board Intake Request**: The maintainer-provided input set for a proposed new board, including environment name,
|
||||
hardware model, display name, target architecture, and optional source materials such as schematics.
|
||||
- **Target Definition Pattern**: A reusable repository convention describing how a board is represented through
|
||||
`variant.h`, optional companion files, PlatformIO environments, and board-specific metadata.
|
||||
- **Evidence Gap**: A missing, ambiguous, or conflicting hardware fact that blocks safe generation of new board support.
|
||||
- **Board Support Scaffold**: The draft output for new hardware support artifacts, limited to fields supported by
|
||||
verified evidence and current repository conventions.
|
||||
|
||||
## Success Criteria _(mandatory)_
|
||||
|
||||
### Measurable Outcomes
|
||||
|
||||
- **SC-001**: Maintainers can locate the common target-definition inputs and pin categories for an existing board in one artifact within 5 minutes, without manually reading multiple variant directories.
|
||||
- **SC-002**: For a representative set of existing boards, the context artifact correctly captures the board environment name, key capability categories, and primary pin groups with no unresolved mismatches after maintainer review.
|
||||
- **SC-003**: A maintainer can submit a new board intake request using the declared minimum inputs and receive a complete list of required board-support artifacts and unresolved evidence gaps in a single workflow pass.
|
||||
- **SC-004**: _(Post-launch metric — not a pre-merge acceptance gate)_ For new board requests with sufficient source evidence, the workflow reduces manual setup time for initial board-support scaffolding by at least 50% compared with manually assembling variant and PlatformIO definitions from scratch. A baseline timed comparison should be conducted after the first production intake.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- The initial increment focuses on repository context and intake/scaffolding workflow support, not full autonomous end-to-end board enablement.
|
||||
- Maintainers using this workflow already have access to the repository, Copilot, and any board source materials they want to reference.
|
||||
- The first implementation may rely on repository-readable sources and manually supplied board details rather than automated PDF parsing.
|
||||
- Existing Meshtastic variant files and PlatformIO environments provide enough representative patterns to build a useful reusable context artifact.
|
||||
- The workflow will be allowed to stop and request clarification when hardware truth is incomplete instead of forcing a guessed output.
|
||||
@@ -0,0 +1,170 @@
|
||||
# Tasks: Hardware Support Agent
|
||||
|
||||
**Branch**: `129-hardware-support-agent`
|
||||
**Input**: Design documents from `specs/129-hardware-support-agent/`
|
||||
**Prerequisites**: plan.md ✅, spec.md ✅, research.md ✅, data-model.md ✅, contracts/board-intake-contract.md ✅
|
||||
|
||||
**Note on existing work**: The Phase 3 (US1) inventory script and generated context artifact already exist.
|
||||
Tasks T001–T004 treat them as in-scope for validation and hardening rather than creation from scratch.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Setup
|
||||
|
||||
**Purpose**: Confirm repository structure and tooling baseline for this feature.
|
||||
|
||||
- [x] T001 Confirm `bin/generate_hardware_support_context.py` executes without errors from the repo root via `python3 bin/generate_hardware_support_context.py`
|
||||
- [x] T002 [P] Confirm `docs/hardware-support-context.md` exists and is committed or tracked in the working tree
|
||||
- [x] T003 [P] Clean up the duplicated `"Where relevant, requirements MUST also state:"` block in `specs/129-hardware-support-agent/spec.md`
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Foundational (Blocking Prerequisites)
|
||||
|
||||
**Purpose**: Shared utilities and data structures that US2 and US3 both depend on.
|
||||
|
||||
**⚠️ CRITICAL**: US2 and US3 cannot begin until this phase is complete.
|
||||
|
||||
- [x] T004 Add a `BoardIntakeRequest` dataclass (or typed dict) capturing the fields from `specs/129-hardware-support-agent/data-model.md` in `bin/board_intake.py`
|
||||
- [x] T005 Add a `EvidenceGap` dataclass in `bin/board_intake.py` matching the data model
|
||||
- [x] T006 Add an `IntakeAssessment` dataclass in `bin/board_intake.py` matching the data model
|
||||
- [x] T007 Implement a `load_hardware_context(path)` helper in `bin/board_intake.py` that reads `docs/hardware-support-context.md` and returns architecture family names and metadata key list for use by the assessment logic
|
||||
|
||||
**Checkpoint**: Shared data structures and context loader in place — US2 and US3 implementation can begin.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: User Story 1 — Build Reusable Hardware Context (Priority: P1) 🎯 MVP
|
||||
|
||||
**Goal**: A single repository-backed markdown document accurately inventories current board-support patterns across all supported architectures so maintainers can start a new board definition from verified patterns.
|
||||
|
||||
**Independent Test**: Run `python3 bin/generate_hardware_support_context.py` and manually spot-check output against four representative variants from different architectures.
|
||||
|
||||
### Validation for User Story 1
|
||||
|
||||
- [x] T008 [P] [US1] Spot-check generated `docs/hardware-support-context.md` against `variants/esp32/tbeam` — confirm radio pins, metadata keys, and category counts match the variant.h and platformio.ini declarations
|
||||
- [x] T009 [P] [US1] Spot-check against `variants/esp32s3/tlora-pager` — confirm all 17 `custom_meshtastic_*` metadata keys and high Connectivity/Other category macro count are reflected
|
||||
- [x] T010 [P] [US1] Spot-check against `variants/nrf52840/t-echo` — confirm nRF52-specific macros (`USE_LFXO`, `VARIANT_MCK`, nRF52-style SPI pins) appear correctly
|
||||
- [x] T011 [P] [US1] Spot-check against `variants/rp2040/rak11310` — confirm RP2040 architecture entry is present and radio pins match
|
||||
- [x] T012 [US1] Run `trunk fmt bin/generate_hardware_support_context.py` and fix any formatting issues
|
||||
|
||||
### Implementation for User Story 1
|
||||
|
||||
- [x] T013 [P] [US1] Add `--validate` CLI flag to `bin/generate_hardware_support_context.py` that prints a summary of how many variants were scanned, how many had metadata keys, and how many had no `variant.h` (for inherited-defaults audit)
|
||||
- [x] T014 [US1] Add a `## Inherited Defaults Note` section to the generated `docs/hardware-support-context.md` that lists architecture families known to rely on BSP/base-environment defaults rather than locally declared macros (informed by validate output)
|
||||
|
||||
**Checkpoint**: `docs/hardware-support-context.md` is validated, formatted, and includes inherited-defaults guidance. US1 fully testable and deliverable independently.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: User Story 2 — Define New Board Intake (Priority: P2)
|
||||
|
||||
**Goal**: A maintainer can provide an environment name, hardware model, display name, and architecture and receive back a structured assessment listing expected artifacts, required metadata, closest matching patterns, and any evidence gaps.
|
||||
|
||||
**Independent Test**: Run the intake workflow against a sample hypothetical board (e.g., a new ESP32-S3 board with only minimum inputs) and confirm it returns a complete assessment with at least one evidence gap identified.
|
||||
|
||||
### Validation for User Story 2
|
||||
|
||||
- [x] T015 [P] [US2] Create `bin/fixtures/intake_minimal.json` with just the required fields for a hypothetical new ESP32-S3 board and confirm `bin/board_intake.py` parses it without error
|
||||
- [x] T016 [P] [US2] Create `bin/fixtures/intake_full.json` with all recommended fields and source materials and confirm the workflow marks `scaffold_ready: true`
|
||||
- [x] T016b [P] [US2] Create `bin/fixtures/intake_multi_env.json` representing a board with two display variants sharing one hardware model (e.g., a TFT and an e-ink variant) and confirm `assess_intake` flags `revision-scope` ambiguity as a blocking Evidence Gap rather than collapsing the options silently
|
||||
- [x] T017 [US2] Confirm `bin/board_intake.py --validate bin/fixtures/intake_minimal.json` correctly flags missing radio, display, and power evidence as blocking gaps
|
||||
|
||||
### Implementation for User Story 2
|
||||
|
||||
- [x] T018 [P] [US2] Implement `validate_intake(request: BoardIntakeRequest) -> list[str]` in `bin/board_intake.py` that checks required fields and detects environment-name conflicts against the existing architecture inventory in `docs/hardware-support-context.md`
|
||||
- [x] T019 [P] [US2] Implement `find_matched_patterns(request: BoardIntakeRequest, context) -> list[dict]` that returns the three closest existing board examples by architecture from the context document
|
||||
- [x] T020 [US2] Implement `build_evidence_gaps(request: BoardIntakeRequest) -> list[EvidenceGap]` that identifies missing pin group evidence (radio, display, GPS, power, input) based on declared source materials
|
||||
- [x] T021 [US2] Implement `assess_intake(request: BoardIntakeRequest, context) -> IntakeAssessment` combining T018–T020 to produce a full structured assessment
|
||||
- [x] T022 [US2] Implement `render_assessment_markdown(assessment: IntakeAssessment) -> str` that formats the assessment as a maintainer-readable markdown report
|
||||
- [x] T023 [US2] Add a CLI entry point `bin/board_intake.py <intake.json>` that prints the assessment markdown to stdout or an output file
|
||||
- [x] T024 [US2] Run `trunk fmt bin/board_intake.py` and fix any formatting issues
|
||||
|
||||
**Checkpoint**: `bin/board_intake.py` fully processes a new board request and prints an assessment. US2 independently testable.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: User Story 3 — Generate Board Support Scaffolding (Priority: P3)
|
||||
|
||||
**Goal**: When intake assessment marks `scaffold_ready: true`, the workflow drafts `variant.h`, optional `variant.cpp`, and PlatformIO environment content using repository conventions, with inline annotations for unresolved items.
|
||||
|
||||
**Independent Test**: Run the scaffold generator for a fully-specified test case and confirm the output files follow existing repository patterns and include `// TODO:` markers for any fields not backed by supplied evidence.
|
||||
|
||||
### Validation for User Story 3
|
||||
|
||||
- [x] T025 [P] [US3] Run scaffold generator for `bin/fixtures/intake_full.json` and confirm `variant.h` output contains required radio pin group, capability macros, and metadata section
|
||||
- [x] T026 [P] [US3] Confirm scaffold generator emits `// TODO: verify —` annotations for any recommended fields absent from the intake fixture
|
||||
- [x] T027 [US3] Confirm generated PlatformIO env block includes all `custom_meshtastic_*` metadata keys from the contract and uses `extends` to reference the correct base environment for the declared architecture
|
||||
|
||||
### Implementation for User Story 3
|
||||
|
||||
- [x] T028 [P] [US3] Create `bin/board_scaffold.py` with a `generate_variant_h(assessment: IntakeAssessment, context) -> str` function that drafts a `variant.h` file using architecture-appropriate macro order from the context document
|
||||
- [x] T029 [P] [US3] Implement `generate_platformio_env(assessment: IntakeAssessment) -> str` in `bin/board_scaffold.py` that emits the PlatformIO environment block with `custom_meshtastic_*` fields
|
||||
- [x] T030 [US3] Implement `annotate_unresolved(content: str, gaps: list[EvidenceGap]) -> str` that inserts `// TODO: verify — {gap.description}` comments next to lines that correspond to unresolved evidence gaps
|
||||
- [x] T031 [US3] Implement `scaffold_board(assessment: IntakeAssessment, context, output_dir: Path)` which orchestrates T028–T030 and writes files to the proposed variant directory path
|
||||
- [x] T032 [US3] Add CLI entry point `bin/board_scaffold.py <intake.json> [--output-dir <path>]` that reads an intake file, runs the full intake + scaffold pipeline, and writes output
|
||||
- [x] T033 [US3] Guard scaffold entry: if `assess_intake` returns `scaffold_ready: false`, print the assessment report and exit with a non-zero code rather than generating files
|
||||
- [x] T034 [US3] Run `trunk fmt bin/board_scaffold.py` and fix any formatting issues
|
||||
|
||||
**Checkpoint**: All three user stories independently functional. Hardware context, intake assessment, and scaffold generation each work as standalone deliverables.
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: Polish & Cross-Cutting Concerns
|
||||
|
||||
**Purpose**: Custom Copilot agent integration, documentation, and final review.
|
||||
|
||||
- [x] T035 [P] Create `.github/prompts/hardware-support.prompt.md` that routes the hardware support workflow to the custom agent
|
||||
- [x] T036 [P] Create `.github/agents/hardware-support.agent.md` with step-by-step instructions for the Copilot hardware-support workflow: context regeneration → intake → assessment → optional scaffold
|
||||
- [x] T037 [US1] Update `specs/129-hardware-support-agent/quickstart.md` Step 3 and Step 4 to reference the completed `bin/board_intake.py` CLI and describe the expected output shape
|
||||
- [x] T038 [P] Confirm that no firmware runtime files under `src/`, `variants/`, or `protobufs/` were modified as part of this feature (constitution compliance check)
|
||||
- [x] T039 Run `python3 bin/generate_hardware_support_context.py` one final time to confirm the regenerated artifact is up to date and passes spot-checks from T008–T011
|
||||
- [x] T040 Summarize any skipped validations, open `// TODO:` items in scaffold output, and any known limitations in `specs/129-hardware-support-agent/plan.md` under a `## Review Notes` section
|
||||
|
||||
---
|
||||
|
||||
## Dependencies & Execution Order
|
||||
|
||||
### Phase Dependencies
|
||||
|
||||
- **Phase 1 (Setup)**: No dependencies — start immediately
|
||||
- **Phase 2 (Foundational)**: Depends on Phase 1 — blocks US2 and US3
|
||||
- **Phase 3 (US1)**: Can start after Phase 1; does not depend on Phase 2
|
||||
- **Phase 4 (US2)**: Depends on Phase 2 (shared data structures)
|
||||
- **Phase 5 (US3)**: Depends on Phase 2 and Phase 4 (uses IntakeAssessment output)
|
||||
- **Phase 6 (Polish)**: Depends on all story phases
|
||||
|
||||
### User Story Dependencies
|
||||
|
||||
- **US1 (P1)**: Depends on Phase 1 only — fully independent MVP
|
||||
- **US2 (P2)**: Depends on Phase 2; integrates with US1 context document but not the script directly
|
||||
- **US3 (P3)**: Depends on Phase 2 and US2 `assess_intake` result
|
||||
|
||||
### Parallel Opportunities
|
||||
|
||||
**Within Phase 2**:
|
||||
|
||||
- T004, T005, T006 can be written in parallel (same file, separate dataclasses — serialize to avoid conflicts)
|
||||
|
||||
**Within Phase 3 (US1)**:
|
||||
|
||||
- T008, T009, T010, T011 (spot-checks) are fully independent and can run in parallel
|
||||
- T013 [P] is independent of validation tasks
|
||||
|
||||
**Within Phase 4 (US2)**:
|
||||
|
||||
- T015, T016 fixture creation can run in parallel
|
||||
- T018 and T019 are independent of each other and can be implemented in parallel
|
||||
|
||||
**Within Phase 5 (US3)**:
|
||||
|
||||
- T028 and T029 are independent scaffold generators — can be written in parallel
|
||||
- T025 and T026 validation tasks are independent
|
||||
|
||||
**Within Phase 6**:
|
||||
|
||||
- T035, T036, T038 are independent files — can all be done in parallel
|
||||
|
||||
### MVP Scope
|
||||
|
||||
To deliver US1 as a standalone MVP: complete Phases 1 and 3 (T001–T003, T008–T014). This verifies the hardware context artifact is accurate and useful without requiring any intake or scaffold tooling.
|
||||
Reference in New Issue
Block a user