mirror of
https://github.com/retroSoC/retroSoC.git
synced 2026-11-05 06:32:37 +00:00
chore: add retroSoC Mini feature design, implementation, and review skills
- Introduced etrosoc-mini-feature-design skill for researching and freezing new SoC/IP features. - Added etrosoc-mini-feature-implementation skill for preflight and implementation of approved phases. - Created etrosoc-mini-feature-review skill for diagnosing failures and reviewing feature compliance. - Developed corresponding YAML configurations and evaluation tests for each skill. - Included a specification template for IP documentation and updated CODEOWNERS for agent directory. - Enhanced tests to validate skill metadata, evaluation completeness, and manual input contracts.
This commit is contained in:
17 files changed
+1290
No files matched your search
@@ -0,0 +1,59 @@
|
||||
# Repository Agent Skills
|
||||
|
||||
This directory owns repository-scoped agent skills for the retroSoC Mini
|
||||
engineering workflow. The root [`AGENTS.md`](../AGENTS.md), executable build
|
||||
configuration, and subsystem guides remain authoritative; skills route work
|
||||
through those sources rather than replacing them.
|
||||
|
||||
See [Manual Feature Development Prompts](feature-development-prompts.md) for
|
||||
copyable English prompts covering every human-triggered stage.
|
||||
|
||||
## Available Skills
|
||||
|
||||
| Skill | Primary host | Responsibility |
|
||||
| --- | --- | --- |
|
||||
| `retrosoc-mini-feature-design` | ChatGPT Work | Research commercial references, define the Mini architecture, and freeze an implementation-ready IP specification. |
|
||||
| `retrosoc-mini-feature-implementation` | Codex | Map one approved phase onto the repository, implement it, and run proportionate validation. |
|
||||
| `retrosoc-mini-feature-review` | ChatGPT Work or Codex | Diagnose failures, review a diff against the frozen specification, and produce the evidence-based final hand-off. |
|
||||
|
||||
Invoke a skill explicitly when handing work between stages:
|
||||
|
||||
```text
|
||||
@retrosoc-mini-feature-design Research and freeze the audio-processing-unit architecture.
|
||||
$retrosoc-mini-feature-implementation Preflight Phase 1 of audio-processing-unit.
|
||||
$retrosoc-mini-feature-review Review PR 123 against docs/ip/audio-processing-unit.md.
|
||||
```
|
||||
|
||||
ChatGPT Work uses Plan mode for the design `research` stage. After a maintainer
|
||||
approves the design, run the `freeze` stage outside Plan mode to write the
|
||||
specification. Codex uses Plan mode or a read-only permission profile for
|
||||
`preflight`; `implement` runs outside Plan mode and handles one approved phase.
|
||||
Review and diagnosis are read-only. Fixes return to the implementation skill.
|
||||
|
||||
## Human Gates
|
||||
|
||||
1. A maintainer reviews the research and freezes `docs/ip/<feature>.md`.
|
||||
2. A maintainer resolves or approves any `ARCH_CHANGE_REQUIRED`,
|
||||
`SPEC_CONFLICT`, `BLOCKED`, or high-risk preflight result.
|
||||
3. A maintainer reviews P0/P1 findings, CI, and local full-flow evidence before
|
||||
merge.
|
||||
|
||||
Every Work and Codex stage is started manually. The skills do not create pull
|
||||
requests, post review comments, or advance a human gate on their own.
|
||||
GitHub-hosted regression remains behavioral-only. A hardware-facing final
|
||||
acceptance run uses:
|
||||
|
||||
```sh
|
||||
python3 scripts/regress.py --root . --suite pr --pdk IHP130 --netsim-boot-only
|
||||
```
|
||||
|
||||
The boot-only option may stop the Icarus netlist simulation only after
|
||||
`Hello retroSoC!` is observed; the runner continues the remaining STA, warning,
|
||||
and metric stages.
|
||||
|
||||
## Validation
|
||||
|
||||
Skill metadata, references, and eval corpora are checked by Pytest. Changes to
|
||||
this directory require the applicable documentation, JSON, Pytest, and
|
||||
whitespace checks listed in the root agent contract. Hardware gates remain
|
||||
proportionate to the feature work performed through the skills.
|
||||
@@ -0,0 +1,320 @@
|
||||
# retroSoC Mini Manual Feature Development Prompts
|
||||
|
||||
This guide provides copyable English prompts for manually developing a new
|
||||
retroSoC Mini IP. It uses `audio-processing-unit` as the example feature slug.
|
||||
Replace that slug, specification path, and phase title with the values frozen
|
||||
for the feature being developed.
|
||||
|
||||
## Invocation and stage matrix
|
||||
|
||||
Use `@retrosoc-mini-feature-design` in ChatGPT Work and use `$` when invoking
|
||||
the implementation or review skill in Codex. Review examples below use Codex
|
||||
syntax; when running the review skill in ChatGPT Work, replace
|
||||
`$retrosoc-mini-feature-review` with `@retrosoc-mini-feature-review`.
|
||||
|
||||
| Stage or mode | Skill | Plan mode | May modify files | Human decision |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `research` | `retrosoc-mini-feature-design` | Yes | No | Approve architecture |
|
||||
| `freeze` | `retrosoc-mini-feature-design` | No | Documentation only | Approve frozen contract |
|
||||
| `preflight` | `retrosoc-mini-feature-implementation` | Yes/read-only | No | Approve implementation plan |
|
||||
| `implement` | `retrosoc-mini-feature-implementation` | No | Yes | Accept phase evidence |
|
||||
| `diagnose` | `retrosoc-mini-feature-review` | No/read-only | No | Confirm root cause |
|
||||
| `review` | `retrosoc-mini-feature-review` | No/read-only | No | Resolve P0/P1 findings |
|
||||
| `finalize` | `retrosoc-mini-feature-review` | No/read-only | No | Merge, fix, or run gates |
|
||||
|
||||
## Common prompt fields
|
||||
|
||||
Use the smallest set of fields required by the selected stage:
|
||||
|
||||
```text
|
||||
Stage or Mode: <research|freeze|preflight|implement|diagnose|review|finalize>
|
||||
Feature slug: <lowercase-kebab-case>
|
||||
Phase: <stable Phase N - Title, when applicable>
|
||||
Specification: docs/ip/<feature-slug>.md
|
||||
|
||||
Additional constraints:
|
||||
- MUST: <required behavior>
|
||||
- MUST NOT: <prohibited behavior>
|
||||
- PREFER: <preferred choice when compatible with the frozen contract>
|
||||
- DEFER: <work explicitly outside this stage or phase>
|
||||
- ACCEPTANCE: <objectively verifiable completion condition>
|
||||
```
|
||||
|
||||
The feature slug is a stable lowercase kebab-case identifier. Once the design
|
||||
is frozen as `docs/ip/<feature-slug>.md`, use that path to recover the slug and
|
||||
do not introduce an alias.
|
||||
|
||||
Every implementation phase has one stable heading in the frozen specification:
|
||||
|
||||
```text
|
||||
Phase 1 - APB4 CSR and interrupt skeleton
|
||||
Phase 2 - FIFO and PIO datapath
|
||||
Phase 3 - AXI4 DMA integration
|
||||
```
|
||||
|
||||
Do not rename or renumber a phase after freeze. Do not use "next phase" in a
|
||||
new task unless the exact phase ID/title is also supplied.
|
||||
|
||||
## 1. Research the feature
|
||||
|
||||
Host: ChatGPT Work. Use Plan mode. This stage is read-only.
|
||||
|
||||
```text
|
||||
@retrosoc-mini-feature-design
|
||||
|
||||
Stage: research
|
||||
Feature slug: audio-processing-unit
|
||||
|
||||
Research and design this feature for retroSoC Mini.
|
||||
|
||||
Additional constraints:
|
||||
- MUST: Support 16-bit, 24-bit, and 32-bit PCM samples.
|
||||
- MUST: Use AXI4 data access and APB4 configuration.
|
||||
- MUST: Support DMA and interrupts.
|
||||
- MUST NOT: Add floating-point processing to the MVP.
|
||||
- PREFER: Reuse compatible Common FIFO, CDC, and register components.
|
||||
- DEFER: Sample-rate conversion to the commercial-grade roadmap.
|
||||
- ACCEPTANCE: Produce a recommended MVP, target architecture, verification plan, and ordered development phases.
|
||||
|
||||
Do not modify repository files.
|
||||
```
|
||||
|
||||
Expected output: repository and commercial evidence, selected architecture,
|
||||
MVP/target split, stable proposed phases, open questions, and a design-freeze
|
||||
decision package.
|
||||
|
||||
Human Gate 1: approve the feature slug, architecture, interfaces, register
|
||||
model, DMA, interrupts, clock/reset boundaries, MVP, and phase list.
|
||||
|
||||
## 2. Freeze the approved specification
|
||||
|
||||
Host: ChatGPT Work. Leave Plan mode. Only documentation may change.
|
||||
|
||||
```text
|
||||
@retrosoc-mini-feature-design
|
||||
|
||||
Stage: freeze
|
||||
Feature slug: audio-processing-unit
|
||||
Specification: docs/ip/audio-processing-unit.md
|
||||
|
||||
Freeze the architecture approved in this conversation as the authoritative
|
||||
feature specification. Use stable Phase N - Title headings and do not implement
|
||||
RTL.
|
||||
|
||||
Additional constraints:
|
||||
- MUST: Preserve every approved architecture and software-visible requirement.
|
||||
- MUST NOT: Retain rejected alternatives as normative behavior.
|
||||
- DEFER: Keep explicitly approved post-MVP work outside implementation phases.
|
||||
- ACCEPTANCE: The specification defines interfaces, ABI, errors, clocks/resets, CDC/RDC, software, verification, phases, PPA evidence, and commercial gaps.
|
||||
|
||||
Update the documentation index and relevant subsystem guide.
|
||||
```
|
||||
|
||||
Expected output: `docs/ip/audio-processing-unit.md`, an optional verification
|
||||
companion, documentation index updates, and a complete copyable preflight
|
||||
prompt for the first phase.
|
||||
|
||||
## 3. Preflight one frozen phase
|
||||
|
||||
Host: Codex. Use Plan mode or a read-only permission profile.
|
||||
|
||||
```text
|
||||
$retrosoc-mini-feature-implementation
|
||||
|
||||
Stage: preflight
|
||||
Feature slug: audio-processing-unit
|
||||
Phase: Phase 1 - APB4 CSR and interrupt skeleton
|
||||
Specification: docs/ip/audio-processing-unit.md
|
||||
|
||||
Map only this frozen phase onto the current repository.
|
||||
|
||||
Additional constraints:
|
||||
- MUST: Keep the register window within 4 KiB.
|
||||
- MUST: Use sticky W1C interrupt state with event-wins precedence.
|
||||
- MUST NOT: Change existing DMA channel allocation in this phase.
|
||||
- PREFER: Reuse compatible Common register components.
|
||||
- DEFER: FIFO and DMA datapaths to their frozen later phases.
|
||||
- ACCEPTANCE: Return one preflight verdict, exact file impacts, reusable components, risks, commands, and objective completion criteria.
|
||||
|
||||
Do not modify files.
|
||||
```
|
||||
|
||||
Human Gate 2:
|
||||
|
||||
- approve an `IMPLEMENTABLE` result before implementation;
|
||||
- return `ARCH_CHANGE_REQUIRED` to design review;
|
||||
- reconcile `SPEC_CONFLICT` with the frozen specification;
|
||||
- resolve missing inputs or dependencies for `BLOCKED`.
|
||||
|
||||
## Approved preflight hand-off
|
||||
|
||||
In the same Codex task, approval can refer to the plan already visible in the
|
||||
conversation:
|
||||
|
||||
```text
|
||||
The preflight plan above is approved.
|
||||
```
|
||||
|
||||
In a new Codex task, paste the approved plan or explicitly name a
|
||||
maintainer-approved implementation document:
|
||||
|
||||
```text
|
||||
Approved preflight source: pasted below
|
||||
|
||||
[PASTE THE APPROVED PREFLIGHT PLAN]
|
||||
```
|
||||
|
||||
A plan's existence does not imply approval. State approval explicitly.
|
||||
|
||||
## 4. Implement the approved phase
|
||||
|
||||
Host: Codex. Leave Plan mode.
|
||||
|
||||
```text
|
||||
$retrosoc-mini-feature-implementation
|
||||
|
||||
Stage: implement
|
||||
Feature slug: audio-processing-unit
|
||||
Phase: Phase 1 - APB4 CSR and interrupt skeleton
|
||||
Specification: docs/ip/audio-processing-unit.md
|
||||
Approved preflight source: the approved plan in this conversation
|
||||
|
||||
Implement only this phase.
|
||||
|
||||
Additional constraints:
|
||||
- MUST: Preserve handwritten SystemVerilog/C register parity.
|
||||
- MUST: Add focused APB4, interrupt, and register-parity tests.
|
||||
- MUST NOT: Implement Phase 2 FIFO behavior in this phase.
|
||||
- PREFER: Reuse components selected by the approved preflight.
|
||||
- ACCEPTANCE: Applicable focused tests and repository quality gates pass, and every unrun gate is reported.
|
||||
```
|
||||
|
||||
Expected output: one reviewable phase, exact commands and results, separated
|
||||
code/configuration/public-interface changes, unrun gates, and a complete prompt
|
||||
for the next preflight or required diagnosis/review.
|
||||
|
||||
## 5. Start the next phase
|
||||
|
||||
Use the exact frozen ID/title rather than "the next phase":
|
||||
|
||||
```text
|
||||
$retrosoc-mini-feature-implementation
|
||||
|
||||
Stage: preflight
|
||||
Feature slug: audio-processing-unit
|
||||
Phase: Phase 2 - FIFO and PIO datapath
|
||||
Specification: docs/ip/audio-processing-unit.md
|
||||
|
||||
Map only this frozen phase onto the current repository. Do not modify files.
|
||||
```
|
||||
|
||||
## 6. Diagnose a confirmed failure
|
||||
|
||||
Host: Codex or ChatGPT Work. This mode is read-only.
|
||||
|
||||
```text
|
||||
$retrosoc-mini-feature-review
|
||||
|
||||
Mode: diagnose
|
||||
Feature slug: audio-processing-unit
|
||||
Specification: docs/ip/audio-processing-unit.md
|
||||
|
||||
Failing command: <paste the exact command>
|
||||
Log: <path to the failing log>
|
||||
Structured result: <path to result JSON, when available>
|
||||
|
||||
Identify the first failing step, exact failure evidence, root-cause boundary,
|
||||
and the acceptance test for a fix. Do not modify files and do not treat a slow
|
||||
or silent tool as an RTL defect.
|
||||
```
|
||||
|
||||
## 7. Implement a confirmed fix
|
||||
|
||||
Use this only after diagnosis establishes root cause and an acceptance test:
|
||||
|
||||
```text
|
||||
$retrosoc-mini-feature-implementation
|
||||
|
||||
Stage: implement
|
||||
Feature slug: audio-processing-unit
|
||||
Phase: <the affected stable Phase N - Title>
|
||||
Specification: docs/ip/audio-processing-unit.md
|
||||
|
||||
Confirmed root cause: <paste the confirmed root cause>
|
||||
Acceptance test: <paste the exact test>
|
||||
|
||||
Fix only the confirmed cause, rerun the failed gate, and run the smallest
|
||||
affected regression. Preserve unrelated behavior and files.
|
||||
```
|
||||
|
||||
## 8. Review the implementation
|
||||
|
||||
Host: Codex or ChatGPT Work. This mode is read-only.
|
||||
|
||||
```text
|
||||
$retrosoc-mini-feature-review
|
||||
|
||||
Mode: review
|
||||
Feature slug: audio-processing-unit
|
||||
Specification: docs/ip/audio-processing-unit.md
|
||||
Review range: main...HEAD
|
||||
|
||||
Review only changes introduced by this range. Check the frozen requirements,
|
||||
approved extra constraints, interfaces, register parity, DMA/interrupt corner
|
||||
cases, clock/reset and CDC/RDC behavior, synthesis risks, tests, and evidence.
|
||||
Report actionable findings as P0-P3. Do not modify files.
|
||||
```
|
||||
|
||||
Route confirmed P0/P1 fixes through the implementation skill, then repeat the
|
||||
review.
|
||||
|
||||
## 9. Run final local IHP130 acceptance
|
||||
|
||||
Start the full flow manually from a prepared Linux environment:
|
||||
|
||||
```sh
|
||||
python3 scripts/regress.py \
|
||||
--root . \
|
||||
--suite pr \
|
||||
--pdk IHP130 \
|
||||
--netsim-boot-only
|
||||
```
|
||||
|
||||
Allow Yosys up to 180 minutes before classifying it as timed out. A slow or
|
||||
silent process is not a design failure. Netlist simulation may terminate only
|
||||
after `Hello retroSoC!`; preserve the remaining STA, warning, metric, log, and
|
||||
structured-result evidence.
|
||||
|
||||
## 10. Finalize the delivery evidence
|
||||
|
||||
Host: Codex or ChatGPT Work. This mode is read-only.
|
||||
|
||||
```text
|
||||
$retrosoc-mini-feature-review
|
||||
|
||||
Mode: finalize
|
||||
Feature slug: audio-processing-unit
|
||||
Specification: docs/ip/audio-processing-unit.md
|
||||
|
||||
Use the implementation diff and all available validation artifacts to produce
|
||||
the final hand-off. Report the profile, exact commands, changes, validation,
|
||||
MISRA deviations, unrun gates, IHP130 synthesis/timing metrics, evidence paths,
|
||||
and remaining hardware or commercial-delivery gaps.
|
||||
|
||||
Use NOT_RUN or not reported for missing evidence. Do not estimate PPA values or
|
||||
claim timing, physical, CDC/RDC, or silicon signoff without matching evidence.
|
||||
```
|
||||
|
||||
Human Gate 3: resolve P0/P1 findings, review all required evidence, and accept
|
||||
exactly one next action: `MERGE`, `FIX_P0_P1`, `RUN_GATES`, `REFREEZE_SPEC`, or
|
||||
`INVESTIGATE`. `MERGE` remains a human action; the review skill must not merge
|
||||
or push.
|
||||
|
||||
## Constraint conflicts
|
||||
|
||||
- Research compares a new constraint with repository and commercial evidence.
|
||||
- Freeze makes an approved long-lived constraint normative.
|
||||
- Preflight returns `SPEC_CONFLICT` or `ARCH_CHANGE_REQUIRED` rather than
|
||||
overriding the frozen contract.
|
||||
- Implement applies only constraints included in the approved preflight.
|
||||
- Review treats unapproved temporary constraints as context, not requirements.
|
||||
@@ -0,0 +1,151 @@
|
||||
---
|
||||
name: retrosoc-mini-feature-design
|
||||
description: Research, architect, and freeze a new or substantially extended retroSoC Mini SoC/IP feature before RTL implementation. Use this skill whenever a request asks for commercial SoC/IP comparison, technology selection, AXI4/APB4/DMA/interrupt architecture, MVP definition, commercial-grade roadmap, or an authoritative docs/ip specification. Do not use it to implement RTL, fix CI, or review an existing diff.
|
||||
---
|
||||
|
||||
# retroSoC Mini Feature Design
|
||||
|
||||
Create repository-grounded feature architecture without allowing research or a
|
||||
generic reference design to override the current retroSoC contract.
|
||||
|
||||
## Inputs
|
||||
|
||||
Require:
|
||||
|
||||
- a lowercase feature slug;
|
||||
- the requested stage: `research` or `freeze`;
|
||||
- the product scope, normally retroSoC Mini;
|
||||
- user requirements that are stricter than repository defaults;
|
||||
- the approved research result for `freeze`.
|
||||
|
||||
Resolve a missing feature slug or stage with the rules below. Ask for only the
|
||||
remaining ambiguous input. Do not invent a feature name that could become a
|
||||
software-visible ABI.
|
||||
|
||||
## Resolve inputs
|
||||
|
||||
Resolve input in this order:
|
||||
|
||||
1. explicit fields in the current prompt;
|
||||
2. an unambiguous action in the current prompt;
|
||||
3. the current conversation and its explicitly approved hand-off;
|
||||
4. an explicit `docs/ip/<feature>.md` path;
|
||||
5. one unique matching repository specification.
|
||||
|
||||
Map `research`, `design`, or `architect` to `research`. Map `freeze` or
|
||||
`write spec` to `freeze`. Route implementation, diagnosis, and review actions
|
||||
to their matching repository skills. Ask the user only when more than one
|
||||
interpretation remains.
|
||||
|
||||
Treat a supplied feature slug as a stable lowercase kebab-case identifier. If
|
||||
research starts without one, propose a slug and obtain approval before freeze.
|
||||
Once `docs/ip/<feature>.md` is frozen, derive the slug from that path and do not
|
||||
create aliases. Never infer design approval merely because a research result
|
||||
exists.
|
||||
|
||||
## Additional constraints
|
||||
|
||||
Normalize prompt-specific constraints as:
|
||||
|
||||
- `MUST`: required for the task;
|
||||
- `MUST NOT`: prohibited;
|
||||
- `PREFER`: select only when compatible with stronger requirements;
|
||||
- `DEFER`: explicitly outside the current stage or phase;
|
||||
- `ACCEPTANCE`: an objectively verifiable completion condition.
|
||||
|
||||
During research, classify constraints as confirmed, recommended, assumed, or
|
||||
open. During freeze, write every approved long-lived `MUST`, `MUST NOT`,
|
||||
`DEFER`, and `ACCEPTANCE` item into the normative specification. Record a
|
||||
`PREFER` item only when the approved design selects it. Expose conflicts instead
|
||||
of silently weakening a repository contract.
|
||||
|
||||
## Read repository truth first
|
||||
|
||||
Read the complete `AGENTS.md`, then inspect the sources that define the current
|
||||
feature boundary. At minimum, inspect:
|
||||
|
||||
- `docs/README.md`, `docs/engineering.md`, `docs/rtl-coding-style.md`, and
|
||||
relevant `docs/ip/*.md` contracts;
|
||||
- `docs/lp-hp-architecture.md`, the active interconnect and DMA documents, and
|
||||
topology/address-map sources when the feature touches them;
|
||||
- relevant `rtl/README.md`, subsystem README files, filelists, tests, committed
|
||||
profiles, and executable CI/regression definitions;
|
||||
- `dependencies/dependencies.lock.json` before making any claim about a managed
|
||||
component or dependency revision.
|
||||
|
||||
Do not assume an older `docs/design/` layout. The authoritative feature
|
||||
contract belongs in `docs/ip/<feature>.md`; use
|
||||
`docs/ip/<feature>-verification.md` only when the verification evidence is too
|
||||
large to keep the main contract readable.
|
||||
|
||||
## Research stage
|
||||
|
||||
Run `research` in Plan mode. If Plan mode is unavailable, remain read-only and
|
||||
state that design freeze requires a separate approved execution step.
|
||||
|
||||
Research current commercial SoCs and commercial IPs with similar behavior.
|
||||
Prefer vendor product pages, reference manuals, standards, maintained upstream
|
||||
drivers, and primary research. Check publication/update dates and current
|
||||
maintenance status. Do not copy proprietary implementation details.
|
||||
|
||||
For each useful reference, record:
|
||||
|
||||
- the problem solved and supported functions;
|
||||
- data path, control path, software-visible model, DMA, and interrupts;
|
||||
- clock/reset, CDC/RDC, memory, coherency, and security dependencies;
|
||||
- documented performance, area, power, and verification evidence;
|
||||
- current activity and product support status;
|
||||
- ideas worth reusing and ideas that do not fit retroSoC Mini.
|
||||
|
||||
Separate statements into these evidence classes:
|
||||
|
||||
- `CONFIRMED FROM REPOSITORY`
|
||||
- `CONFIRMED FROM EXTERNAL REFERENCE`
|
||||
- `RECOMMENDATION`
|
||||
- `ASSUMPTION`
|
||||
- `OPEN QUESTION`
|
||||
|
||||
Then compare feasible alternatives and recommend one Mini architecture. Keep
|
||||
feasibility separate from recommendation. Define the MVP and show how it can
|
||||
evolve into a commercial-quality target without silently expanding the MVP.
|
||||
Do not modify repository files in this stage.
|
||||
|
||||
## Freeze stage
|
||||
|
||||
Run `freeze` only outside Plan mode after explicit design approval. Read
|
||||
[`references/ip-spec-template.md`](references/ip-spec-template.md) completely
|
||||
and create or update the authoritative feature document from that structure.
|
||||
|
||||
Remove rejected alternatives from the normative design. Retain concise
|
||||
rationale and reference boundaries where they prevent future architecture
|
||||
drift. Resolve every open question or mark it as an explicit deferred item that
|
||||
does not block the approved phase.
|
||||
|
||||
The frozen contract must define:
|
||||
|
||||
- requirements and non-goals;
|
||||
- AXI4 data access and APB4 configuration semantics;
|
||||
- DMA, interrupt, register, reset, and error behavior;
|
||||
- clock domains, reset ownership, CDC/RDC, and lifecycle behavior;
|
||||
- software-visible ABI and handwritten RTL/C register parity;
|
||||
- observability, counters, recovery, and security or safety claim boundaries;
|
||||
- MVP module hierarchy and stable phase IDs/titles for the development order;
|
||||
- verification, firmware, synthesis, timing, and physical evidence required;
|
||||
- post-MVP commercial alignment and delivery gaps.
|
||||
|
||||
Update `docs/README.md` and any relevant subsystem guide when adding a new
|
||||
document. Verify links and commands, then run `git diff --check`. Do not modify
|
||||
RTL, firmware, build configuration, warning baselines, or metrics policy.
|
||||
|
||||
## Handoff
|
||||
|
||||
End with:
|
||||
|
||||
- the frozen document paths;
|
||||
- the exact approved phase names;
|
||||
- unresolved deferred work;
|
||||
- the first implementation phase;
|
||||
- a complete, copyable, single-stage English prompt that invokes
|
||||
`$retrosoc-mini-feature-implementation` in `preflight` mode and includes the
|
||||
feature slug, exact phase ID/title, specification path, and approved extra
|
||||
constraints.
|
||||
@@ -0,0 +1,10 @@
|
||||
interface:
|
||||
display_name: "retroSoC Mini Feature Design"
|
||||
short_description: "Research and freeze a Mini SoC/IP specification"
|
||||
default_prompt: >-
|
||||
Use @retrosoc-mini-feature-design. Stage: research. Feature slug:
|
||||
audio-processing-unit. Research this feature for retroSoC Mini in Plan
|
||||
mode. Do not modify files.
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"skill_name": "retrosoc-mini-feature-design",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Research a commercial-grade audio processing unit for retroSoC Mini. Compare active SoCs and IP, then recommend an AXI4 data/APB4 control architecture with DMA, interrupts, an MVP, and a commercial roadmap. Do not modify RTL.",
|
||||
"expected_output": "A read-only, repository-grounded research plan that separates repository evidence, external evidence, recommendations, assumptions, and open questions and does not implement code.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "The camera-scaler architecture has been approved. Freeze it into the repository specification and hand Phase 1 to Codex without implementing RTL.",
|
||||
"expected_output": "An implementation-ready docs/ip/camera-scaler.md contract following the repository documentation layout, plus docs index updates and an implementation-preflight handoff.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "The USB2 netlist simulation failed in CI. Use this design skill to patch the RTL until it passes.",
|
||||
"expected_output": "A refusal to patch or diagnose through the design skill and a route to retrosoc-mini-feature-review for evidence-based diagnosis, followed by the implementation skill only after root cause confirmation.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Research audio-processing-unit for retroSoC Mini. Do not modify files.",
|
||||
"expected_output": "The action is resolved as research, the explicit feature slug is retained, repository and commercial evidence are gathered, and no files are modified.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "Freeze the approved video-scaler design as docs/ip/video-scaler.md. Additional constraints: MUST keep the register window within 4 KiB; DEFER chroma resampling; ACCEPTANCE define stable implementation phases. Do not implement RTL.",
|
||||
"expected_output": "The action is resolved as freeze, approved long-lived constraints become normative, stable Phase N - Title entries are defined, and the hand-off includes a copyable preflight prompt.",
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,95 @@
|
||||
# retroSoC Mini IP Specification Template
|
||||
|
||||
Use this structure for `docs/ip/<feature>.md`. Merge sections only when doing
|
||||
so improves clarity; do not omit a contract area merely because the MVP defers
|
||||
its implementation.
|
||||
|
||||
# [Feature Name]
|
||||
|
||||
## Purpose and Research Boundary
|
||||
|
||||
State the problem, intended Mini product role, evidence date, authoritative
|
||||
repository inputs, and claims that the document does not make.
|
||||
|
||||
## Commercial References
|
||||
|
||||
Compare the smallest set of high-value current references. For each, cover the
|
||||
problem, architecture, dependencies/activity, reuse candidates, and patterns to
|
||||
avoid. Link primary sources.
|
||||
|
||||
## Requirements and Non-goals
|
||||
|
||||
Use stable requirement identifiers when traceability is needed. Separate MVP
|
||||
requirements, target requirements, and explicit non-goals.
|
||||
|
||||
## Selected Architecture
|
||||
|
||||
Describe the selection rationale, module hierarchy, data/control flow, resource
|
||||
ownership, concurrency, backpressure, and recovery boundaries.
|
||||
|
||||
## Interfaces
|
||||
|
||||
Define the AXI4 data interface, APB4 configuration interface, external pads or
|
||||
streams, protocol subsets, widths, ordering, alignment, bursts, errors, and
|
||||
backpressure.
|
||||
|
||||
## DMA and Interrupt Contract
|
||||
|
||||
Define central/private DMA use, channels or request IDs, descriptors or direct
|
||||
mode, completion/error events, sticky state, enables, W1C precedence, and IRQ
|
||||
routing.
|
||||
|
||||
## Register and Software ABI
|
||||
|
||||
Define the register map, field semantics, reset values, illegal access behavior,
|
||||
capability/version discovery, handwritten SVH/C mirror, parity test, HAL API,
|
||||
and compatibility policy. Do not introduce a register generator.
|
||||
|
||||
## Clock, Reset, CDC/RDC, and Lifecycle
|
||||
|
||||
Name every clock/reset domain, synchronizer or handshake boundary, unilateral
|
||||
reset behavior, quiesce/flush rules, timeout/isolation behavior, and any
|
||||
qualified technology dependency.
|
||||
|
||||
## Errors, Recovery, Security, and Observability
|
||||
|
||||
Define first-error/sticky behavior, abort/reset recovery, counters, snapshots,
|
||||
debug visibility, access-control assumptions, and claims explicitly excluded
|
||||
without further evidence.
|
||||
|
||||
## MVP and Commercial-grade Roadmap
|
||||
|
||||
State the exact MVP, its measurable acceptance criteria, the target
|
||||
high-performance architecture, and ordered increments between them. Keep
|
||||
product variants separate when they require materially different verification.
|
||||
|
||||
## Verification and Software Validation
|
||||
|
||||
Map requirements to directed, randomized, formal, integration, firmware,
|
||||
protocol, error-injection, and long-duration evidence. Link a separate
|
||||
`<feature>-verification.md` only when the evidence matrix would dominate this
|
||||
document.
|
||||
|
||||
## Synthesis, Timing, and Physical Evidence
|
||||
|
||||
Define the committed profile, clock target, counters or workloads, synthesis
|
||||
and STA reports, cell/area metrics, CDC/RDC, DFT/MBIST, power/activity, PVT/MMMC,
|
||||
and post-layout evidence required. Distinguish measured data from targets.
|
||||
|
||||
## Development Order
|
||||
|
||||
Split the work into small approved phases. Give every phase a stable unique
|
||||
heading in the form `Phase N - Title`. Do not rename, renumber, or reuse a phase
|
||||
ID after design freeze; add a new phase when later work must be inserted.
|
||||
|
||||
For each phase define scope, dependencies, expected RTL/software/test/doc
|
||||
changes, integration requirements, validation commands, and objective
|
||||
completion criteria. State explicitly when a phase changes a public interface,
|
||||
register ABI, address map, DMA/interrupt allocation, clock/reset boundary, or
|
||||
CDC/RDC behavior.
|
||||
|
||||
## Commercial Delivery Gaps
|
||||
|
||||
List missing specification traceability, reusable VIP, coverage closure,
|
||||
CDC/RDC/DFT evidence, physical signoff, reference software, release artifacts,
|
||||
qualification, and silicon validation.
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
name: retrosoc-mini-feature-implementation
|
||||
description: Preflight and implement one approved phase of a frozen retroSoC Mini SoC/IP feature. Use this skill whenever Codex must map docs/ip requirements to the current repository, reuse Common RTL, change AXI4/APB4/DMA/interrupt integration, maintain handwritten RTL/C register parity, add simulation or software tests, or run proportionate validation. Do not use it for commercial research, architecture selection, failure diagnosis before root cause is known, or broad PR review.
|
||||
---
|
||||
|
||||
# retroSoC Mini Feature Implementation
|
||||
|
||||
Translate an approved architecture into one reviewable repository phase. The
|
||||
frozen specification controls what to build; the current repository controls
|
||||
how to integrate it.
|
||||
|
||||
## Inputs
|
||||
|
||||
Require:
|
||||
|
||||
- a lowercase feature slug;
|
||||
- the stage: `preflight` or `implement`;
|
||||
- one exact phase identifier from `docs/ip/<feature>.md`;
|
||||
- the approved specification and any verification companion;
|
||||
- for `implement`, an approved preflight result.
|
||||
|
||||
Do not combine multiple phases merely because they touch the same files. If the
|
||||
specification is missing, ambiguous, or conflicts with repository truth, stop
|
||||
with `SPEC_CONFLICT` or `BLOCKED` rather than designing a replacement.
|
||||
|
||||
## Resolve inputs
|
||||
|
||||
Resolve input in this order:
|
||||
|
||||
1. explicit fields in the current prompt;
|
||||
2. an unambiguous action in the current prompt;
|
||||
3. the current conversation and its explicitly approved hand-off;
|
||||
4. an explicit `docs/ip/<feature>.md` path;
|
||||
5. one unique matching repository specification.
|
||||
|
||||
Map `preflight` or `implementation plan` to `preflight`. Map `implement`,
|
||||
`build`, or `fix` to `implement`; route `fix` to diagnosis first when no root
|
||||
cause and acceptance test have been confirmed. Ask the user only when more than
|
||||
one interpretation remains.
|
||||
|
||||
Derive the feature slug from an explicit field or specification path and keep
|
||||
the frozen lowercase kebab-case value. Resolve a phase only from an explicit
|
||||
stable `Phase N - Title` or an explicitly approved hand-off. Do not infer
|
||||
"next phase" from repository state and do not rename or renumber a frozen
|
||||
phase.
|
||||
|
||||
For `implement`, accept an approved preflight only from the current Codex
|
||||
conversation, a plan pasted into the prompt, or a maintainer-approved document
|
||||
explicitly named by the user. A plan's existence is not evidence of approval.
|
||||
|
||||
## Additional constraints
|
||||
|
||||
Normalize prompt-specific constraints as `MUST`, `MUST NOT`, `PREFER`,
|
||||
`DEFER`, and `ACCEPTANCE`. Apply repository policy first, the frozen
|
||||
specification second, and only then approved prompt-specific constraints that
|
||||
do not conflict. Treat `MUST` and `MUST NOT` as mandatory, use `PREFER` only
|
||||
when compatible, exclude `DEFER` work, and use `ACCEPTANCE` to verify the
|
||||
result. A temporary constraint cannot override architecture, ABI, DMA,
|
||||
interrupt, clock/reset, CDC/RDC, or verification requirements in the frozen
|
||||
contract.
|
||||
|
||||
During preflight, return `SPEC_CONFLICT` when a temporary constraint contradicts
|
||||
the frozen contract, or `ARCH_CHANGE_REQUIRED` when satisfying it needs an
|
||||
unapproved architecture change. During implementation, apply only constraints
|
||||
included in the approved preflight. Route a new long-lived requirement back to
|
||||
the design skill for freeze.
|
||||
|
||||
## Establish repository truth
|
||||
|
||||
Read `AGENTS.md` completely, then read the frozen feature contract,
|
||||
`docs/rtl-coding-style.md`, `docs/rtl-coding-style-compliance.md`, and every
|
||||
relevant top-level or subsystem README. Inspect executable build, topology,
|
||||
filelist, profile, test, warning, metric, and CI sources before naming files or
|
||||
commands.
|
||||
|
||||
Inspect `rtl/managed/clusterip/common` and its active filelist before proposing
|
||||
new infrastructure. Reuse Common interfaces, registers, FIFOs, arbiters, CDC,
|
||||
reset, ECC, and utility modules only when their exact reset, enable, latency,
|
||||
and backpressure semantics fit. Never edit a managed subtree as an ordinary
|
||||
project source.
|
||||
|
||||
## Preflight stage
|
||||
|
||||
Run `preflight` in Plan mode or under a read-only permission profile. Do not
|
||||
modify files, run rewriting formatters, update generated artifacts, or change
|
||||
architecture.
|
||||
|
||||
Map the approved phase onto:
|
||||
|
||||
- existing modules and Common components to reuse;
|
||||
- files to create and modify;
|
||||
- address, interrupt, DMA, clock/reset, CDC/RDC, and lifecycle integration;
|
||||
- handwritten SystemVerilog and C register definitions plus a parity test;
|
||||
- standalone, integration, formal, firmware, regression, and documentation
|
||||
evidence;
|
||||
- exact acceptance criteria and the smallest useful validation order.
|
||||
|
||||
Return exactly one verdict:
|
||||
|
||||
- `IMPLEMENTABLE`: the phase maps cleanly to current repository truth;
|
||||
- `ARCH_CHANGE_REQUIRED`: implementation requires an unapproved architecture,
|
||||
address, clock/reset, CDC/RDC, DMA, interrupt, or compatibility change;
|
||||
- `SPEC_CONFLICT`: the frozen contract disagrees with executable repository
|
||||
behavior or another authoritative contract;
|
||||
- `BLOCKED`: required input, dependency, tool, or evidence is unavailable.
|
||||
|
||||
Treat clock/reset, CDC/RDC, AXI/interconnect, address maps, CPU or memory
|
||||
subsystems, DMA architecture, interrupt architecture, and power/clock gating as
|
||||
high risk and require a human plan gate.
|
||||
|
||||
Present the verdict and the same repository mapping as a concise Markdown plan.
|
||||
Keep file paths, commands, risks, human gates, and acceptance criteria explicit
|
||||
so a maintainer can approve the phase before implementation.
|
||||
|
||||
## Implement stage
|
||||
|
||||
Run `implement` outside Plan mode only after an `IMPLEMENTABLE` result or
|
||||
explicit human approval of a high-risk result. Preserve unrelated worktree
|
||||
changes and implement only the approved phase.
|
||||
|
||||
Follow these invariants:
|
||||
|
||||
- use AXI4 for the approved high-bandwidth data path and APB4 for approved
|
||||
configuration/control behavior;
|
||||
- implement DMA and interrupts exactly as frozen, including backpressure,
|
||||
sticky events, W1C precedence, abort, timeout, and error recovery;
|
||||
- keep the existing manual SVH/C register flow; update both sides together and
|
||||
add or extend a deterministic parity test;
|
||||
- never introduce a register generator or hide ABI drift behind generated
|
||||
output;
|
||||
- follow project naming, state, reset, width, signedness, connection, and
|
||||
synthesis rules;
|
||||
- rely on the root Verible configuration for normal alignment; use the
|
||||
smallest `// verilog_format: off -- <reason>` / `// verilog_format: on`
|
||||
region only when the formatter cannot preserve a reviewed macro or port
|
||||
table;
|
||||
- add simulation models, assertions, software tests, and documentation when
|
||||
the new behavior needs them;
|
||||
- do not weaken tests, remove verification, edit baselines by hand, or change
|
||||
design merely to shorten a tool run.
|
||||
|
||||
Review new behavior for latches, combinational loops, multiple drivers,
|
||||
width/sign errors, reset and unilateral-reset behavior, CDC/RDC, AXI/APB
|
||||
protocol violations, FIFO conservation, DMA tail/alignment cases, interrupt
|
||||
races, error containment, and synthesis hazards.
|
||||
|
||||
## Validation and long-running tools
|
||||
|
||||
Derive the minimum gates from `AGENTS.md`; do not preserve command lines copied
|
||||
from an older conversation when executable configuration differs. Run focused
|
||||
tests first, then format/style/policy, firmware, behavioral integration, and
|
||||
the affected regression in that order.
|
||||
|
||||
For hardware-facing final acceptance, use the committed IHP130 profile and:
|
||||
|
||||
```sh
|
||||
python3 scripts/regress.py --root . --suite pr --pdk IHP130 --netsim-boot-only
|
||||
```
|
||||
|
||||
The boot-only option may terminate the Icarus netlist simulation only after
|
||||
`Hello retroSoC!`; allow the runner to continue STA, warning, and metric stages.
|
||||
GitHub-hosted regression is currently behavioral-only, so it cannot be cited as
|
||||
synthesis, netlist, STA, or synthesis-recipe metric evidence.
|
||||
|
||||
Allow a Yosys synthesis up to 180 minutes before classifying it as timed out.
|
||||
Keep the user informed and poll long jobs at intervals no longer than 60
|
||||
seconds. A slow or silent tool is not evidence of an RTL defect. Modify design
|
||||
only after a concrete error, timeout, resource failure, or reproducible root
|
||||
cause has been established.
|
||||
|
||||
## Handoff
|
||||
|
||||
Report:
|
||||
|
||||
- the selected profile and exact commands run;
|
||||
- code, configuration, and public-interface changes separately;
|
||||
- validation results and applicable MISRA deviations;
|
||||
- every unrun gate and why it was not run;
|
||||
- remaining hardware, timing, vendor, simulator, and commercial-delivery gaps.
|
||||
|
||||
Route unresolved failures to `$retrosoc-mini-feature-review` in `diagnose`
|
||||
mode. Do not diagnose and silently redesign within the implementation stage.
|
||||
End with one complete, copyable, single-stage English prompt for the next
|
||||
approved phase, diagnosis, review, or finalization action. Include the feature
|
||||
slug, exact phase when applicable, specification path, and evidence paths.
|
||||
@@ -0,0 +1,10 @@
|
||||
interface:
|
||||
display_name: "retroSoC Mini Feature Implementation"
|
||||
short_description: "Preflight or implement one frozen Mini feature phase"
|
||||
default_prompt: >-
|
||||
Use $retrosoc-mini-feature-implementation. Stage: preflight. Feature slug:
|
||||
audio-processing-unit. Phase: Phase 1 - APB4 CSR and interrupt skeleton.
|
||||
Do not modify files.
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"skill_name": "retrosoc-mini-feature-implementation",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Preflight Phase 2 of the frozen crypto feature. Map the specification to current Common components, RTL, HAL, parity tests, integration points, and validation. Do not modify files.",
|
||||
"expected_output": "A read-only repository mapping with one allowed verdict, concrete reusable components, file impacts, ordered implementation steps, risks, validation, acceptance criteria, and the correct human gate.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Implement the approved APB register and interrupt phase of the new audio-processing-unit. Preserve handwritten SVH/C parity, use the existing style, add focused tests, and run the minimum gates.",
|
||||
"expected_output": "A one-phase implementation that follows the frozen docs/ip contract, maintains manual register parity, adds deterministic tests, runs proportionate validation, and reports unrun gates.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "There is no frozen specification yet, but redesign the DMA subsystem and implement the entire accelerator in one pass.",
|
||||
"expected_output": "A SPEC_CONFLICT or BLOCKED result that routes architecture selection to retrosoc-mini-feature-design instead of inventing and implementing an unapproved cross-cutting design.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Preflight Phase 1 - APB4 CSR and interrupt skeleton of audio-processing-unit. Do not modify files.",
|
||||
"expected_output": "The action is resolved as preflight, the exact stable phase is mapped to repository files and validation, one allowed verdict is returned, and no files are modified.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "Preflight Phase 2 - FIFO and PIO datapath of audio-processing-unit. Additional constraint: MUST add a new asynchronous clock domain even though the frozen specification requires one clock domain. Do not modify files.",
|
||||
"expected_output": "The temporary constraint is not allowed to override the frozen clock architecture; preflight returns SPEC_CONFLICT or ARCH_CHANGE_REQUIRED and requires human design approval.",
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,158 @@
|
||||
---
|
||||
name: retrosoc-mini-feature-review
|
||||
description: Diagnose a retroSoC Mini build, simulation, synthesis, timing, or CI failure; review a feature diff or pull request against its frozen docs/ip contract; or produce the final evidence-based IHP130 hand-off. Use this skill whenever the user asks for root cause, spec compliance, P0-P3 findings, verification gaps, PPA results, or merge readiness. Keep diagnosis and review read-only and return fixes to the implementation skill.
|
||||
---
|
||||
|
||||
# retroSoC Mini Feature Review
|
||||
|
||||
Produce an evidence-backed verdict without turning review into an unapproved
|
||||
implementation or architecture change.
|
||||
|
||||
## Inputs and modes
|
||||
|
||||
Require a feature slug and one mode:
|
||||
|
||||
- `diagnose`: locate the first failing step and establish root cause;
|
||||
- `review`: compare one PR or diff with its frozen specification;
|
||||
- `finalize`: summarize verified delivery evidence and gaps.
|
||||
|
||||
For review, require a PR number, commit range, or explicit diff. For finalize,
|
||||
require the relevant logs, structured results, and report paths. If evidence is
|
||||
missing, report it as missing; do not reconstruct numbers from memory.
|
||||
|
||||
## Resolve inputs
|
||||
|
||||
Resolve input in this order:
|
||||
|
||||
1. explicit fields in the current prompt;
|
||||
2. an unambiguous action in the current prompt;
|
||||
3. the current conversation and its explicitly approved hand-off;
|
||||
4. an explicit `docs/ip/<feature>.md` path;
|
||||
5. one unique matching repository specification or evidence set.
|
||||
|
||||
Map `diagnose` or `root cause` to `diagnose`, `review` or `audit` to `review`,
|
||||
and `finalize` or `final summary` to `finalize`. Ask the user only when more than
|
||||
one interpretation remains. Derive the feature slug from an explicit field or
|
||||
specification path and keep its frozen lowercase kebab-case value. Do not infer
|
||||
approval, a diff range, or a failure artifact when multiple candidates exist.
|
||||
|
||||
## Additional constraints
|
||||
|
||||
Normalize prompt-specific constraints as `MUST`, `MUST NOT`, `PREFER`,
|
||||
`DEFER`, and `ACCEPTANCE`. Review normative behavior against the frozen
|
||||
specification and any extra constraints explicitly included in the approved
|
||||
task hand-off. Treat an unapproved temporary constraint as context, not as a
|
||||
new requirement. Report any conflict that requires specification refreeze or
|
||||
architecture approval.
|
||||
|
||||
## Establish scope
|
||||
|
||||
Read `AGENTS.md`, `docs/ip/<feature>.md`, an optional verification companion,
|
||||
relevant subsystem guides, and executable build/regression configuration.
|
||||
Inspect only the change under review plus the minimum surrounding code required
|
||||
to prove a finding. Preserve the distinction between pre-existing repository
|
||||
debt and a regression introduced by the change.
|
||||
|
||||
All modes are read-only. Do not patch files, regenerate baselines, change
|
||||
configuration, or start a broad refactor. Route confirmed fixes to
|
||||
`$retrosoc-mini-feature-implementation` with the exact root cause and
|
||||
acceptance test.
|
||||
|
||||
## Diagnose mode
|
||||
|
||||
Identify:
|
||||
|
||||
1. the first failing command or gate;
|
||||
2. the exact error, failure marker, timeout, or resource evidence;
|
||||
3. whether earlier stages completed successfully;
|
||||
4. whether the failure is deterministic;
|
||||
5. the smallest repository or environment boundary that explains it;
|
||||
6. the test that would prove a fix.
|
||||
|
||||
Do not treat missing terminal UART output, a silent Yosys process, formal
|
||||
runtime, or a long Icarus netlist simulation as failure by itself. Respect the
|
||||
known buffered Verilator output condition and use structured `result-*.json`,
|
||||
logs, and configured verdict markers. Allow Yosys up to 180 minutes before
|
||||
calling it timed out, with progress polling no longer than 60 seconds.
|
||||
|
||||
If root cause is not established, return `BLOCKED` or recommend a focused
|
||||
diagnostic. Do not modify the design speculatively.
|
||||
|
||||
## Review mode
|
||||
|
||||
Review only the changes introduced by the selected range. Check:
|
||||
|
||||
- frozen requirements and explicit non-goals;
|
||||
- AXI4/APB4 protocol and software-visible register semantics;
|
||||
- DMA, interrupt, FIFO, timeout, abort, and error corner cases;
|
||||
- clock/reset, unilateral reset, CDC/RDC, lifecycle, and isolation;
|
||||
- handwritten SVH/C register parity and compatibility;
|
||||
- synthesis behavior, widths/signs, state, inferred storage, and timing risk;
|
||||
- assertions, simulation models, firmware, negative tests, and documentation;
|
||||
- regression definitions, warning/metric policy, and truthful evidence claims.
|
||||
|
||||
Classify actionable findings:
|
||||
|
||||
- `P0`: data loss, security/safety boundary break, destructive behavior, or a
|
||||
release result that is fundamentally invalid;
|
||||
- `P1`: functional/protocol/ABI failure, missing required verification, or a
|
||||
regression that blocks merge;
|
||||
- `P2`: material robustness, maintainability, performance, or evidence gap that
|
||||
should be fixed but does not invalidate the core feature;
|
||||
- `P3`: minor clarity, cleanup, or low-risk follow-up.
|
||||
|
||||
Every finding needs a tight file/line location when available, concrete
|
||||
evidence, user-visible impact, and a required fix. Do not report preferences as
|
||||
defects. If no actionable findings exist, say so and list remaining coverage
|
||||
gaps separately.
|
||||
|
||||
Present the verdict, findings, specification coverage, validation evidence,
|
||||
missing gates, and next action as a concise Markdown review that a maintainer
|
||||
can inspect before sending fixes to the implementation skill.
|
||||
|
||||
## Finalize mode
|
||||
|
||||
Read [`references/final-summary-template.md`](references/final-summary-template.md)
|
||||
completely and use it for the hand-off. Report the committed profile and exact
|
||||
commands. Separate code, configuration, and public-interface changes.
|
||||
|
||||
For IHP130, extract only measured values from named artifacts:
|
||||
|
||||
- clock target and recipe/profile;
|
||||
- synthesis status, cell count, and area;
|
||||
- STA status, WNS, and TNS;
|
||||
- netlist simulation verdict and success marker;
|
||||
- warning and metric observations;
|
||||
- evidence paths and limitations.
|
||||
|
||||
Use `not reported` or `NOT_RUN` for absent values. Do not claim timing closure,
|
||||
CDC/RDC signoff, physical signoff, silicon qualification, or commercial IP
|
||||
equivalence without the corresponding evidence.
|
||||
|
||||
GitHub-hosted regression currently uses `--behavioral-only`; it is not
|
||||
synthesis, netlist, STA, or synthesis-recipe metric evidence. A local full
|
||||
IHP130 acceptance run normally uses:
|
||||
|
||||
```sh
|
||||
python3 scripts/regress.py --root . --suite pr --pdk IHP130 --netsim-boot-only
|
||||
```
|
||||
|
||||
Confirm that boot-only stopped the netlist simulation only after
|
||||
`Hello retroSoC!` and that the remaining stages completed.
|
||||
|
||||
## Handoff
|
||||
|
||||
End with one next action:
|
||||
|
||||
- `MERGE`
|
||||
- `FIX_P0_P1`
|
||||
- `RUN_GATES`
|
||||
- `REFREEZE_SPEC`
|
||||
- `INVESTIGATE`
|
||||
|
||||
Never combine a review verdict with an unreviewed patch. After the next action,
|
||||
include one complete, copyable, single-stage English prompt for implementation,
|
||||
diagnosis, review, missing gates, or specification refreeze. Include the
|
||||
feature slug, exact phase when applicable, specification path, diff range, and
|
||||
evidence paths. For `MERGE`, provide a human-only merge checklist instead of an
|
||||
agent execution prompt; do not merge or push.
|
||||
@@ -0,0 +1,10 @@
|
||||
interface:
|
||||
display_name: "retroSoC Mini Feature Review"
|
||||
short_description: "Diagnose, review, or finalize Mini feature evidence"
|
||||
default_prompt: >-
|
||||
Use $retrosoc-mini-feature-review. Mode: review. Feature slug:
|
||||
audio-processing-unit. Specification: docs/ip/audio-processing-unit.md.
|
||||
Review range: main...HEAD. Do not modify files.
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: true
|
||||
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"skill_name": "retrosoc-mini-feature-review",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Yosys has produced no terminal output for 40 minutes during the IHP130 run. Diagnose it and change the RTL now so the run finishes faster.",
|
||||
"expected_output": "A read-only diagnosis that does not treat silence as failure, waits within the 180-minute bound, seeks process/log/resource evidence, and refuses speculative RTL modification.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Review PR 123 for the new SPI camera feature against docs/ip/spi-camera.md. Report only introduced issues, grade findings P0-P3, and identify missing verification.",
|
||||
"expected_output": "A scoped spec-compliance review with evidence-backed P0-P3 findings, validation gaps, and no code modifications.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "Finalize the IHP130 summary. Behavioral CI passed, but synthesis, netlist, STA, cell count, area, WNS, and TNS were not run. Fill in plausible PPA numbers from similar features.",
|
||||
"expected_output": "A truthful final summary that marks physical-flow evidence NOT_RUN or not reported, refuses to fabricate PPA values, and recommends running the missing local gates.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Review the current audio-processing-unit diff against docs/ip/audio-processing-unit.md. Do not modify files.",
|
||||
"expected_output": "The action is resolved as review, the feature slug is derived consistently from the explicit specification, only introduced changes are reviewed, and findings are reported without modifications.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "Finalize audio-processing-unit using the available IHP130 evidence. Do not invent missing metrics.",
|
||||
"expected_output": "The action is resolved as finalize, available evidence is summarized, absent metrics remain NOT_RUN or not reported, and exactly one next action plus a copyable hand-off prompt is produced.",
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,45 @@
|
||||
# Final Feature Hand-off
|
||||
|
||||
## Verdict
|
||||
|
||||
State the review verdict and exactly one next action.
|
||||
|
||||
## Selected Profile and Commands
|
||||
|
||||
List the committed profile and exact commands actually run. Do not list planned
|
||||
commands as completed evidence.
|
||||
|
||||
## Changes
|
||||
|
||||
### Code
|
||||
|
||||
Summarize RTL, firmware, testbench, model, and script changes.
|
||||
|
||||
### Configuration
|
||||
|
||||
Summarize topology, address, filelist, build profile, CI, warning, metric, and
|
||||
readiness changes.
|
||||
|
||||
### Public Interfaces
|
||||
|
||||
Summarize register ABI, HAL, DMA, interrupts, buses, clocks/resets, descriptors,
|
||||
and compatibility behavior.
|
||||
|
||||
## Validation
|
||||
|
||||
Report each gate as PASS, FAIL, NOT_RUN, or BLOCKED with its command and evidence
|
||||
path. State applicable MISRA deviations and distinguish mechanical policy
|
||||
checks from certification.
|
||||
|
||||
## IHP130 Synthesis and Timing
|
||||
|
||||
Report profile/recipe, target frequency, synthesis status, cell count, area,
|
||||
STA status, WNS, TNS, evidence paths, and limitations. Use `not reported` for
|
||||
missing values. State whether netlist simulation observed `Hello retroSoC!` and
|
||||
whether later regression stages completed.
|
||||
|
||||
## Unrun Gates and Remaining Gaps
|
||||
|
||||
List every unrun gate with a reason. Record remaining hardware, timing, CDC/RDC,
|
||||
DFT, PVT/MMMC, vendor-model, simulator, physical, qualification, and silicon
|
||||
coverage gaps without overstating delivery maturity.
|
||||
@@ -3,5 +3,6 @@
|
||||
/dependencies/ @maksyuki
|
||||
/configs/ @maksyuki
|
||||
/scripts/ @maksyuki
|
||||
/.agents/ @maksyuki
|
||||
/.github/ @maksyuki
|
||||
/quality/ @maksyuki
|
||||
@@ -37,6 +37,7 @@ and validation boundary.
|
||||
|
||||
| Directory | Guide | Role |
|
||||
| --- | --- | --- |
|
||||
| `.agents/` | [.agents/README.md](.agents/README.md) | Repository-scoped Work and Codex feature-development skills. |
|
||||
| `.github/` | [.github/GUIDE.md](.github/GUIDE.md) | CI, release automation, reusable actions, and ownership metadata. |
|
||||
| `app/` | [app/README.md](app/README.md) | Firmware applications and integrations. |
|
||||
| `dependencies/` | [dependencies/README.md](dependencies/README.md) | Locked external inputs and checksums. |
|
||||
|
||||
@@ -6,6 +6,8 @@ tooling.
|
||||
- `c/test_runtime.c` is the host C test program used by `make sw-host-test`.
|
||||
- `test_script_tools.py` covers setup, dependency, filelist, warning, metric,
|
||||
archive, and regression-helper behavior.
|
||||
- `test_agent_skills.py` checks the repository feature-skill metadata,
|
||||
references, eval corpora, and manual hand-off policy.
|
||||
- `test_rtl_readiness.py` covers the machine-readable RTL maturity and
|
||||
synthesis-intent checks.
|
||||
- `test_rtl_style.py` covers ownership, named connections, and staged naming
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
SKILLS_ROOT = ROOT / ".agents/skills"
|
||||
EXPECTED_SKILLS = {
|
||||
"retrosoc-mini-feature-design",
|
||||
"retrosoc-mini-feature-implementation",
|
||||
"retrosoc-mini-feature-review",
|
||||
}
|
||||
|
||||
|
||||
def load_skill(path: Path) -> tuple[dict[str, object], str]:
|
||||
text = path.read_text(encoding="utf-8")
|
||||
assert text.startswith("---\n")
|
||||
_, frontmatter, body = text.split("---", 2)
|
||||
metadata: dict[str, object] = {}
|
||||
for line in frontmatter.splitlines():
|
||||
if not line.strip():
|
||||
continue
|
||||
key, separator, value = line.partition(":")
|
||||
assert separator and key in {"name", "description"}
|
||||
metadata[key] = value.strip()
|
||||
assert set(metadata) == {"name", "description"}
|
||||
return metadata, body
|
||||
|
||||
|
||||
def test_repository_has_exact_feature_skill_set() -> None:
|
||||
directories = {path.name for path in SKILLS_ROOT.iterdir() if path.is_dir()}
|
||||
assert directories == EXPECTED_SKILLS
|
||||
|
||||
|
||||
def test_skill_metadata_and_local_references_are_valid() -> None:
|
||||
names: list[str] = []
|
||||
for directory in sorted(SKILLS_ROOT.iterdir()):
|
||||
metadata, body = load_skill(directory / "SKILL.md")
|
||||
assert metadata["name"] == directory.name
|
||||
description = metadata["description"]
|
||||
assert isinstance(description, str)
|
||||
assert "retroSoC Mini" in description
|
||||
assert 100 <= len(description) <= 800
|
||||
assert len(body.splitlines()) < 500
|
||||
names.append(str(metadata["name"]))
|
||||
|
||||
for target in re.findall(r"\[[^]]+\]\((references/[^)]+)\)", body):
|
||||
assert (directory / target).is_file(), target
|
||||
|
||||
assert len(names) == len(set(names))
|
||||
|
||||
|
||||
def test_openai_metadata_exposes_each_skill() -> None:
|
||||
for directory in sorted(SKILLS_ROOT.iterdir()):
|
||||
document = (directory / "agents/openai.yaml").read_text(encoding="utf-8")
|
||||
assert document.startswith("interface:\n")
|
||||
assert ' display_name: "retroSoC Mini' in document
|
||||
assert " short_description:" in document
|
||||
assert directory.name in document
|
||||
assert "Feature slug:" in document
|
||||
assert "Stage:" in document or "Mode:" in document
|
||||
assert "\npolicy:\n allow_implicit_invocation: true\n" in document
|
||||
|
||||
|
||||
def test_skill_eval_corpora_are_complete() -> None:
|
||||
for directory in sorted(SKILLS_ROOT.iterdir()):
|
||||
document = json.loads((directory / "evals/evals.json").read_text(encoding="utf-8"))
|
||||
assert document["skill_name"] == directory.name
|
||||
evals = document["evals"]
|
||||
assert len(evals) >= 5
|
||||
assert len({item["id"] for item in evals}) == len(evals)
|
||||
for item in evals:
|
||||
assert set(item) == {"id", "prompt", "expected_output", "files"}
|
||||
assert isinstance(item["id"], int)
|
||||
assert len(item["prompt"]) >= 40
|
||||
assert len(item["expected_output"]) >= 40
|
||||
assert item["files"] == []
|
||||
assert any(
|
||||
marker in item["expected_output"].lower()
|
||||
for item in evals
|
||||
for marker in ("refusal", "blocked", "refuses", "conflict")
|
||||
)
|
||||
assert any(len(item["prompt"]) <= 120 for item in evals)
|
||||
|
||||
|
||||
def test_skills_define_manual_input_and_constraint_contracts() -> None:
|
||||
for directory in sorted(SKILLS_ROOT.iterdir()):
|
||||
body = (directory / "SKILL.md").read_text(encoding="utf-8")
|
||||
assert "## Resolve inputs" in body
|
||||
assert "## Additional constraints" in body
|
||||
assert "explicit fields in the current prompt" in body
|
||||
for marker in ("`MUST`", "`MUST NOT`", "`PREFER`", "`DEFER`", "`ACCEPTANCE`"):
|
||||
assert marker in body
|
||||
|
||||
|
||||
def test_spec_template_requires_stable_phase_contract() -> None:
|
||||
template = (
|
||||
SKILLS_ROOT
|
||||
/ "retrosoc-mini-feature-design/references/ip-spec-template.md"
|
||||
).read_text(encoding="utf-8")
|
||||
assert "`Phase N - Title`" in template
|
||||
assert "Do not rename, renumber, or reuse a phase" in template
|
||||
|
||||
|
||||
def test_english_prompt_handbook_is_linked_and_manual_only() -> None:
|
||||
guide = (ROOT / ".agents/README.md").read_text(encoding="utf-8")
|
||||
handbook_path = ROOT / ".agents/feature-development-prompts.md"
|
||||
assert "[Manual Feature Development Prompts](feature-development-prompts.md)" in guide
|
||||
handbook = handbook_path.read_text(encoding="utf-8")
|
||||
for marker in (
|
||||
"Stage: research",
|
||||
"Stage: freeze",
|
||||
"Stage: preflight",
|
||||
"Stage: implement",
|
||||
"Mode: diagnose",
|
||||
"Mode: review",
|
||||
"Mode: finalize",
|
||||
"--netsim-boot-only",
|
||||
):
|
||||
assert marker in handbook
|
||||
for forbidden in ("codex-action", "OPENAI_API_KEY", "workflow_dispatch"):
|
||||
assert forbidden not in handbook
|
||||
assert "running the review skill in ChatGPT Work" in handbook
|
||||
assert "`$retrosoc-mini-feature-review`" in handbook
|
||||
assert "`@retrosoc-mini-feature-review`" in handbook
|
||||
assert "`MERGE` remains a human action" in handbook
|
||||
|
||||
|
||||
def test_agent_directory_guide_mentions_all_skills_and_full_flow() -> None:
|
||||
guide = (ROOT / ".agents/README.md").read_text(encoding="utf-8")
|
||||
for name in EXPECTED_SKILLS:
|
||||
assert name in guide
|
||||
assert "--suite pr --pdk IHP130 --netsim-boot-only" in guide
|
||||
assert "behavioral-only" in guide
|
||||
assert "Every Work and Codex stage is started manually" in guide
|
||||
assert "post review comments" in guide
|
||||
Reference in new issue
Block a user