OpenSpec Flow — RP2350 Platform

0Initialize the repository

Run once at the repository root.

npm install -g @fission-ai/openspec@latest
cd rp2350-platform
openspec init

Recommended structure

rp2350-platform/
├── openspec/
│   ├── specs/                 # Current platform truth
│   └── changes/               # Proposed and active changes
├── engine/
├── games/
│   └── dog-catch/
├── boards/
├── tools/
├── tests/
└── docs/

1Explore

Use exploration when requirements, hardware constraints, or architecture are still unclear.

/opsx:explore

Explore adding a tile-based rendering system to the RP2350 engine.
Consider:
- non-PSRAM and PSRAM boards
- HSTX HDMI output
- SRAM budget
- DMA and PIO usage
- 30 fps and 60 fps targets
- reusable engine boundaries

Agent contributions

Chief Architect Embedded Engineer Graphics Engineer Engine Steward Gameplay Engineer

Exit condition

The problem is clearly stated.
Platform vs. game ownership is understood.
Primary constraints are identified.
Open decisions are explicit.

2Propose

Create the formal change package once the problem is sufficiently understood.

/opsx:propose add-tile-renderer

Typical change folder:

openspec/changes/add-tile-renderer/
├── proposal.md
├── design.md
├── tasks.md
└── specs/
    └── tile-rendering/
        └── spec.md

Recommended artifact sequence: proposal → specs → design → tasks.

3Review the change package

proposal.md — why and scope

Problem being solved
Why now
Included / excluded scope
Affected capabilities
Risks and dependencies

spec.md — observable requirements

Behavioral scenarios
Acceptance criteria
Measurable embedded constraints
No hidden implementation assumptions

design.md — how it works

Component boundaries and APIs
Memory ownership
DMA / PIO / core allocation
Data formats and fallback paths
Performance budgets
Rejected alternatives

tasks.md — implementation sequence

Small, independently verifiable work items
Clear ordering and dependencies
Platform validation tasks
Documentation and integration work

Human approval gate: approve platform-vs-game ownership, public API, memory/performance budgets, acceptance scenarios, scope/exclusions, and task breakdown before implementation begins.

4Apply

/opsx:apply add-tile-renderer

The implementing agent should read the approved proposal, specs, design, and tasks before writing code.

Implement tasks in order.
Mark tasks complete as evidence accumulates.
Run tests after meaningful increments.
Stay within approved scope.

The code must follow the spec. If the spec is wrong, update the spec explicitly before changing implementation direction.

5Verify

/opsx:verify add-tile-renderer

Verification dimensions

Functional: every specification scenario passes.
Architectural: engine boundaries remain clean.
Embedded: flash, SRAM, heap, stack, frame time, DMA/PIO, CPU usage.
Quality: tests, static analysis, docs, and task completion.

QA/Test Engineer owns evidence; Engine Steward confirms reusable-platform integrity.

6Sync

/opsx:sync add-tile-renderer

Reconcile legitimate spec changes with what is ready to become durable platform truth.

openspec/specs/
    Describes what the platform supports now.

openspec/changes/add-tile-renderer/
    Describes the proposed difference from current state.

7Archive

/opsx:archive add-tile-renderer

# or
openspec archive add-tile-renderer

Archive only after implementation, verification, architectural review, and spec reconciliation are complete.

All required tasks checked
Acceptance scenarios pass
Hardware validation recorded
Architecture review passes
Canonical specs match the finished platform

Recommended multi-agent operating model

Producer defines the desired outcome and initiates the change.
Chief Architect + specialists run Explore and identify constraints.
Chief Architect drives Propose and owns the change framing.
Domain agents contribute to specs and design.
Engine Steward reviews reusable boundaries and APIs.
Human technical/creative lead approves the package.
Implementing agents run Apply and complete tasks.
QA/Test Engineer verifies against specs and budgets.
Chief Architect + Engine Steward review final implementation and spec changes.
Producer confirms completion and archives the change.

Ownership matrix

Artifact	Primary owner	Required reviewers
`proposal.md`	Producer / Chief Architect	Human lead
`spec.md`	Domain engineer	QA, Engine Steward
`design.md`	Chief Architect	Relevant specialists
`tasks.md`	Implementing engineer	Producer, QA
Code	Assigned engineering agent	Domain reviewer
Verification evidence	QA/Test Engineer	Chief Architect
Archive approval	Producer	Human lead

Everyday command sequence

For a moderately complex feature:

/opsx:explore
/opsx:propose add-tile-renderer

# Human + agent review

/opsx:apply add-tile-renderer
/opsx:verify add-tile-renderer
/opsx:sync add-tile-renderer
/opsx:archive add-tile-renderer

Quick path

Use only for narrow, well-understood changes with no architectural or hardware-budget impact.

/opsx:propose fix-controller-deadzone
/opsx:apply fix-controller-deadzone
/opsx:archive fix-controller-deadzone

Good fits: bug fixes, docs, small tooling changes.

Recommended OpenSpec Flow