From ce147a84ecabff5f73c5e15a53fddbb6e8de1368 Mon Sep 17 00:00:00 2001 From: IonutMuthi Date: Wed, 22 Apr 2026 11:43:09 +0300 Subject: [PATCH 1/2] claude: added task refinement skill Added 2 new custom slash commands: * /clarify-task : used for turning an idea into a more detailed version it creates a bried of the task after * /design-task : used to create a design document for the development of a task idealy a brief of the task from /clarify-task is used as a parameter but can be used with a detailed description provided by the user Signed-off-by: IonutMuthi --- .../.claude-plugin/plugin.json | 2 +- .../scopy_dev_plugin/commands/clarify-task.md | 125 ++++++++++++ .../scopy_dev_plugin/commands/design-task.md | 193 ++++++++++++++++++ .../skills/external-research/SKILL.md | 127 ++++++++++++ .../scopy-architecture-knowledge/SKILL.md | 186 +++++++++++++++++ .../scopy-component-relationships/SKILL.md | 170 +++++++++++++++ .../skills/scopy-decision-frameworks/SKILL.md | 177 ++++++++++++++++ .../skills/scopy-tools-inventory/SKILL.md | 135 ++++++++++++ 8 files changed, 1114 insertions(+), 1 deletion(-) create mode 100644 tools/scopy_dev_plugin/commands/clarify-task.md create mode 100644 tools/scopy_dev_plugin/commands/design-task.md create mode 100644 tools/scopy_dev_plugin/skills/external-research/SKILL.md create mode 100644 tools/scopy_dev_plugin/skills/scopy-architecture-knowledge/SKILL.md create mode 100644 tools/scopy_dev_plugin/skills/scopy-component-relationships/SKILL.md create mode 100644 tools/scopy_dev_plugin/skills/scopy-decision-frameworks/SKILL.md create mode 100644 tools/scopy_dev_plugin/skills/scopy-tools-inventory/SKILL.md diff --git a/tools/scopy_dev_plugin/.claude-plugin/plugin.json b/tools/scopy_dev_plugin/.claude-plugin/plugin.json index f5257168fb..dc96dd61ea 100644 --- a/tools/scopy_dev_plugin/.claude-plugin/plugin.json +++ b/tools/scopy_dev_plugin/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "scopy_dev_plugin", - "version": "1.0.0", + "version": "1.2.0", "description": "Scopy development tools: code generation, documentation, testing, quality checks, and styling for IIO plugin development.", "author": { "name": "Muthi Ionut Adrian" } } diff --git a/tools/scopy_dev_plugin/commands/clarify-task.md b/tools/scopy_dev_plugin/commands/clarify-task.md new file mode 100644 index 0000000000..fa95f6ed24 --- /dev/null +++ b/tools/scopy_dev_plugin/commands/clarify-task.md @@ -0,0 +1,125 @@ +# /clarify-task — Refine a vague Scopy development task into a structured task brief + +> **Recommended model:** Opus — this command performs deep codebase exploration and multi-step reasoning to produce high-quality task briefs. + +You are helping the user turn a vague or incomplete development idea into a concrete, actionable task brief for the Scopy project. + +**Raw task description:** `$ARGUMENTS` + +## Step 0: Load context + +Load these knowledge skills by reading their SKILL.md files: +- `scopy-architecture-knowledge` — core architecture patterns +- `scopy-component-relationships` — how components interact +- `scopy-decision-frameworks` — architectural decision trees +- `external-research` — guidelines for researching external solutions + +## Step 1: Initial analysis + +Classify the task into one or more categories: +- **New plugin/package** — creating something from scratch +- **Modification to existing plugin** — changing existing functionality +- **Core infrastructure change** — modifying shared libraries +- **Tooling/CI change** — build system, scripts, CI pipelines +- **Documentation** — docs, tests, guides +- **Cross-cutting concern** — affects multiple modules + +Based on classification, identify which Scopy modules/packages are likely involved: +- Use the Glob tool to find relevant source files and headers +- Use the Grep tool to search for related patterns, class names, or keywords +- Read key files (plugin headers, tool classes, CMakeLists.txt) to understand current state + +If the task mentions external technologies, unfamiliar concepts, or problems that might have existing solutions outside Scopy: +- Use web search or Context7 to gather context +- Check `https://analogdevicesinc.github.io` for ADI hardware/driver documentation +- Note findings for inclusion in the task brief + +## Step 2: Clarifying questions + +Ask **3-6 clarifying questions**, one at a time, using the AskUserQuestion tool. Each question should be informed by what you learned from code exploration. + +**Question categories (use as needed, not a fixed script):** + +1. **Scope** — "What exactly should change? What should NOT change?" + - Informed by: what you found in the code (e.g., "I see the ADC plugin has 3 tools — are we adding to an existing tool or creating a new one?") + +2. **Users** — "Who uses this feature?" + - Options: end user (Scopy GUI), developer (code/API), tester (automation), CI system + +3. **Constraints** — "Are there hardware requirements, platform considerations, or performance needs?" + - Informed by: device compatibility, IIO attributes available, cross-platform concerns + +4. **Integration** — "How does this interact with existing plugins/tools?" + - Informed by: MessageBroker topics, shared widgets, library dependencies + +5. **Success criteria** — "How do we know it's done? What does 'working' look like?" + - Help the user define concrete acceptance criteria + +6. **Priority/timeline** — "Is this blocking something? What's the urgency?" + +**Guidelines:** +- Prefer multiple-choice questions (use AskUserQuestion options) when possible +- One question per message — do not combine questions +- Adapt based on previous answers — skip irrelevant categories +- Reference specific code/files you found during exploration to make questions concrete + +## Step 3: Deep exploration + +After all questions are answered, do a final targeted code exploration: +- Read relevant plugin/library source files identified during Q&A +- Identify existing patterns, utilities, or widgets that can be reused +- Find similar implementations in other plugins (cross-reference) +- Search externally if the task requires technology or patterns not in the codebase +- Note any potential conflicts or dependencies + +## Step 4: Generate task brief + +Present the following structured task brief in the conversation: + +```markdown +## Task Brief: + +**Type:** +**Modules affected:** +**Summary:** <2-3 sentence refined description of what needs to be done> + +### Requirements +- +- +- ... + +### Existing Resources +- — +- ... + +### External Resources (if applicable) +- — +- ... + +### Key Decisions Made +- +- ... + +### Open Questions (if any) +- + +### Suggested Next Step +> Run `/scopy_dev_plugin:design-task` with this brief to generate a full design document with architectural choices, component design, and testing strategy. +``` + +## Step 5: Save (optional) + +Ask the user if they want to save the task brief: + +> "Would you like me to save this task brief to `docs/design/YYYY-MM-DD--brief.md`?" + +If yes, write the file. Do NOT commit — let the user decide when to commit. + +## Rules + +- Do NOT write any code or modify source files — this command produces only a task brief +- Do NOT skip the clarifying questions phase — even if the task seems clear, validate with the user +- Do NOT ask more than 6 questions — consolidate if needed +- Always explore the codebase before asking questions — informed questions are better questions +- Always check for external solutions when the task involves unfamiliar technology +- Reference specific files and line numbers when discussing existing code diff --git a/tools/scopy_dev_plugin/commands/design-task.md b/tools/scopy_dev_plugin/commands/design-task.md new file mode 100644 index 0000000000..7b2271c42e --- /dev/null +++ b/tools/scopy_dev_plugin/commands/design-task.md @@ -0,0 +1,193 @@ +# /design-task — Generate an architectural design document for a Scopy development task + +> **Recommended model:** Opus — this command performs complex architectural reasoning and produces detailed design documents. + +You are creating a detailed design document for a Scopy development task. The input may be a refined task brief (from `/clarify-task`) or a direct task description. + +**Task description:** `$ARGUMENTS` + +## Step 0: Load context + +Load ALL knowledge skills by reading their SKILL.md files: +- `scopy-architecture-knowledge` — core architecture patterns +- `scopy-tools-inventory` — available development tools +- `scopy-component-relationships` — how components interact +- `scopy-decision-frameworks` — architectural decision trees +- `external-research` — guidelines for researching external solutions + +Check if a task brief exists in `docs/design/` matching the topic: +- Use Glob to search for `docs/design/*brief.md` files +- If found, read it and use it as the primary input + +If `$ARGUMENTS` appears vague or underspecified (no concrete requirements, unclear scope): +- Suggest running `/scopy_dev_plugin:clarify-task` first +- But do NOT block — proceed if the user wants to continue + +## Step 1: Architecture analysis + +Using the decision frameworks skill, work through key architectural decisions: + +1. **Where does this belong?** + - Which package, plugin, or core library? + - Use the "Plugin vs Core Library" and "New Package vs Extend Existing" decision trees + +2. **What components need to be created vs modified?** + - Use Glob/Grep to find existing files that will be affected + - Read relevant source files to understand current structure + +3. **What patterns from the codebase apply?** + - ToolTemplate, IIOWidgetBuilder, MessageBroker, Preferences, etc. + - Use the "Tool vs Section", "IIOWidget vs Custom Widget", "Sync vs Async" decision trees + +4. **What external dependencies are needed?** + - If any, follow external-research skill guidelines + - Check license compatibility, cross-platform support + +**Present 2-3 architectural approaches** with trade-offs and your recommendation. Use AskUserQuestion to let the user choose. Format: + +```markdown +### Approach A: (Recommended) +- **How it works:** +- **Pros:** +- **Cons:** + +### Approach B: +- **How it works:** +- **Pros:** +- **Cons:** +``` + +**Wait for user to choose before continuing.** + +## Step 2: Component design + +For the chosen approach, detail each component: + +### New Classes +For each new class: +- **Name** (following Scopy conventions: PascalCase, m_ prefix for members) +- **Responsibility** (single responsibility) +- **Inheritance** (PluginBase, ApiObject, QWidget, etc.) +- **Key methods** (with signatures) +- **File location** (following lowercase filename convention) + +### Modified Classes +For each modified class: +- **File path** and current structure +- **What changes** and why +- **Impact** on other consumers of this class + +### File Locations +Map all new and modified files: +``` +packages//plugins// +├── include// +│ ├── newclass.h (NEW) +│ └── existingclass.h (MODIFIED) +├── src/ +│ ├── newclass.cpp (NEW) +│ └── existingclass.cpp (MODIFIED) +├── CMakeLists.txt (MODIFIED if explicit file lists) +└── test/ + └── tst_newfeature.cpp (NEW) +``` + +### Data Flow +Describe how components communicate: +- Qt signals/slots connections +- MessageBroker topics (if cross-plugin) +- IIO data flow (attribute read/write, buffer streaming) +- API exposure for test automation + +### Configuration +- CMake changes needed (new targets, dependencies, flags) +- manifest.json changes (if any) +- Preferences entries (if any) + +## Step 3: Existing tools & patterns report + +Using the tools inventory skill, categorize what's available: + +### Reusable (use directly) +- Existing utilities, widgets, or patterns that solve part of the problem +- Reference specific files and explain how to use them + +### Adaptable (modify slightly) +- Things that exist but need small changes +- Explain what changes are needed and why + +### Missing (build from scratch) +- What doesn't exist and must be created +- Estimate relative complexity (simple/moderate/complex) + +### External (from outside Scopy) +- Libraries or patterns found via research +- Use the format from the external-research skill +- Include "build it ourselves" as an alternative + +## Step 4: Testing & documentation strategy + +### Unit Tests +- What to test with Qt Test framework +- Mock strategy (if applicable) +- File locations in `test/` subdirectory + +### JS Hardware-in-the-Loop Tests +- What to test with JS HITL (patterns from `claude_scopy_dev_plugin` branch) +- API methods needed for automation +- Hardware requirements + +### Manual Test Cases +- RST test documentation with UIDs and RBP priority levels +- Category A (automatable), B (visual), C (manual only) breakdown + +### API Class +- Is a Q_INVOKABLE API class needed? +- What methods to expose +- Conversion rules for IIO attributes + +### Documentation +- User guide sections (RST format) +- What's New entry for releases + +## Step 5: Present design + +Present the full design in conversation, organized as: + +1. **Architecture Overview** — chosen approach, component diagram +2. **Component Details** — new/modified classes, file locations +3. **Data Flow** — how components communicate +4. **Existing Tools Report** — reusable/adaptable/missing/external +5. **Testing Strategy** — unit, HITL, manual, API +6. **Implementation Order** — suggested sequence of implementation steps + +Ask after each major section: "Does this look right so far?" using AskUserQuestion. + +## Step 6: Save design document + +Ask the user: +> "Would you like me to save this design document to `docs/design/YYYY-MM-DD--design.md`?" + +If yes, write the complete design document to file. + +## Step 7: Transition + +After the design is complete and saved, suggest next steps: + +> **Next steps:** +> - Run the `writing-plans` skill to create a detailed implementation plan from this design +> - Or use specific commands for individual pieces: +> - `/scopy_dev_plugin:create-api ` for the API class +> - `/scopy_dev_plugin:create-docs ` for documentation +> - `/scopy_dev_plugin:create-automated-tests ` for test automation + +## Rules + +- Do NOT write any code or modify source files — this command produces only a design document +- Always present 2-3 approaches before detailing one — let the user choose +- Always check for existing patterns before proposing new ones +- Always evaluate external solutions using the external-research skill criteria +- Reference specific files and line numbers when discussing existing code +- Follow Scopy naming conventions in all proposed class/file names +- Include testing strategy — every feature needs a test plan +- The design document should be detailed enough that someone could implement from it diff --git a/tools/scopy_dev_plugin/skills/external-research/SKILL.md b/tools/scopy_dev_plugin/skills/external-research/SKILL.md new file mode 100644 index 0000000000..bf223dbd55 --- /dev/null +++ b/tools/scopy_dev_plugin/skills/external-research/SKILL.md @@ -0,0 +1,127 @@ +--- +name: external-research +description: Guidelines for using Context7, web search, and other research tools to find solutions outside the Scopy codebase. Loaded when the task involves unfamiliar technology or external libraries. +--- + +# External Research Guidelines + +## When to Search Externally + +Search outside the Scopy codebase when: +- The task mentions technology not currently used in Scopy +- A third-party library could solve the problem better than custom code +- The task references protocols, standards, or algorithms you need documentation for +- You need hardware/driver documentation for a specific ADI device +- A Qt pattern or technique might exist that the codebase doesn't currently use +- Signal processing algorithms need reference implementations + +## Where to Look + +### ADI Hardware & Driver Documentation +**Primary source:** `https://analogdevicesinc.github.io` +- Device datasheets and user guides +- Linux IIO driver documentation +- Reference design documentation +- HDL/FPGA documentation + +**Use when:** Task involves a specific ADI device, IIO driver attributes, hardware capabilities, or register maps. + +### Qt Documentation +**Use Context7 or web search for:** +- Qt5 class reference (widgets, signals/slots, threading) +- Qt design patterns (Model/View, State Machine, Animation) +- QML integration patterns +- Cross-platform considerations + +**Use when:** Building UI components, choosing between Qt approaches, or using Qt classes not currently in the codebase. + +### libiio Documentation +**Use web search for:** +- libiio API reference +- IIO attribute types and conventions +- Context/device/channel hierarchy +- Buffer management patterns + +**Use when:** Working with IIO device communication, attribute reads/writes, or buffer management. + +### GNU Radio Documentation +**Use Context7 or web search for:** +- Block development patterns +- Flowgraph design +- Signal processing blocks reference +- Custom block creation + +**Use when:** Task involves data streaming, signal processing pipelines, or extending gr-util. + +### GitHub Reference Implementations +**Search GitHub for:** +- Similar Qt5 applications with relevant features +- IIO-based tools and utilities +- Signal processing implementations +- Plugin architectures in C++/Qt + +**Use when:** Need a reference implementation to understand an approach. + +### General Web Search +**Use for:** +- Algorithm documentation (DSP, FFT, filtering) +- C++17 patterns and best practices +- CMake integration patterns for third-party libraries +- Cross-platform build considerations + +## How to Evaluate External Solutions + +Before recommending any external library or tool, check: + +### License Compatibility +Scopy is **LGPL-licensed**. Compatible licenses: +- LGPL (any version) — fully compatible +- MIT, BSD, Apache 2.0 — compatible +- GPL — **CAUTION**: only compatible if dynamically linked or the feature is optional +- Proprietary — **NOT compatible** + +### Technical Requirements +- **Qt5 compatibility** — must work with Qt 5.x (not Qt 6-only) +- **Cross-platform** — must support Windows, Linux, macOS (Android is a plus) +- **CMake** — must integrate with CMake build system +- **C++17** — must compile with C++17 standard +- **No conflicting dependencies** — check against existing dependency list (libiio, QWT, Boost, GNU Radio, libsigrokdecode) + +### Quality Indicators +- Actively maintained (commits in last 6 months) +- Has releases/tags (not just raw commits) +- Has tests +- Has documentation +- Used by other projects (stars, forks) +- Responsive maintainers (issue response time) + +## How to Report External Findings + +When presenting external solutions, use this format: + +```markdown +### External Option: +- **What it does:** +- **License:** — +- **Platforms:** +- **Source:** +- **Pros:** + - + - +- **Cons:** + - + - +- **Integration effort:** — +- **Alternative:** +``` + +## Research Workflow + +1. **Understand the need** — What problem does the external solution solve? +2. **Search internally first** — Does Scopy already have something similar? +3. **Search externally** — Use the sources above +4. **Evaluate** — License, compatibility, quality +5. **Compare** — External solution vs building it ourselves +6. **Recommend** — Present options with trade-offs, include "build it ourselves" as an option + +Always present "build it ourselves" alongside external options so the user can make an informed choice. diff --git a/tools/scopy_dev_plugin/skills/scopy-architecture-knowledge/SKILL.md b/tools/scopy_dev_plugin/skills/scopy-architecture-knowledge/SKILL.md new file mode 100644 index 0000000000..465a88b416 --- /dev/null +++ b/tools/scopy_dev_plugin/skills/scopy-architecture-knowledge/SKILL.md @@ -0,0 +1,186 @@ +--- +name: scopy-architecture-knowledge +description: Core Scopy architecture knowledge including plugin lifecycle, library dependencies, build system, and key design patterns. Loaded by clarify-task and design-task commands. +--- + +# Scopy Architecture Knowledge + +## Plugin Lifecycle + +Plugins inherit from `PluginBase` (which implements `Plugin` interface). Required overrides: + +```cpp +bool compatible(QString param, QString category) override; // Device detection (MUST NOT alter state) +bool onConnect() override; // Setup when device connects +bool onDisconnect() override; // Cleanup when device disconnects +``` + +**Full lifecycle sequence:** +1. `DeviceFactory::build(param, category)` creates DeviceImpl +2. DeviceImpl calls `compatible(param, category)` on each plugin factory instance +3. For compatible plugins: `clone()` → `preload()` (NOT on UI thread) +4. `loadIcon()` → `loadPage()` → `loadConfigPage()` → `loadToolList()` → `loadPreferencesPage()` → `loadExtraButtons()` → `postload()` +5. On device connect: `onConnect()` — enable tools, create instruments, register APIs +6. On device disconnect: `onDisconnect()` — cleanup, delete APIs + +**Plugin class skeleton:** +```cpp +class MyPlugin : public QObject, PluginBase { + SCOPY_PLUGIN + Q_OBJECT + Q_PLUGIN_METADATA(IID "org.adi.Scopy.PluginBase") + Q_INTERFACES(scopy::PluginBase) + +public: + bool compatible(QString m_param, QString category) override; + void loadToolList() override; + bool loadIcon() override; + bool loadPage() override; + bool onConnect() override; + bool onDisconnect() override; + void initMetadata() override; +}; +``` + +## Core Library Dependency Chain + +Build order and what each library provides: + +| Library | Provides | Key Dependencies | +|---------|----------|-----------------| +| `scopy-common` | Shared utilities, base classes | Qt Core/Widgets | +| `scopyiioutil` | IIO communication, PingTask, CyclicalTask | libiio, libserialport | +| `scopy-gui` | Qt widgets, UI components, Style system | scopy-common, QWT, Boost | +| `scopy-gr-util` | GNU Radio integration | scopy-iioutil, scopy-gui, Gnuradio libs, Genalyzer | +| `scopy-pluginbase` | Plugin framework, MessageBroker, Preferences, ScopyJS | scopy-common, scopyiioutil | +| `scopy-iio-widgets` | IIOWidgetBuilder, IIOWidget, IIOWidgetGroup | libiio, scopy-gui, scopyiioutil | +| `scopy-pkg-manager` | Runtime package installation | — | +| `scopy-core` | ScopyMainWindow, DeviceManager, PluginManager, DeviceFactory | all above, Python3, libsigrokdecode | + +## Package Structure + +Each package lives under `packages//` and contains: +``` +packages// +├── manifest.json.cmakein # Package metadata (id, title, version, category) +├── CMakeLists.txt # Build config +├── plugins/ # One or more plugins +│ └── / +│ ├── include//plugin.h +│ ├── src/plugin.cpp +│ ├── CMakeLists.txt +│ ├── resources/ +│ ├── test/ +│ └── doc/ +└── emu-xml/ # Device emulation files +``` + +**Build flags:** `ENABLE_PACKAGE_` (uppercase, dashes preserved). `ENABLE_ALL_PACKAGES=ON` enables all. + +## ToolMenuEntry + +Tools are registered in `loadToolList()` using the macro: +```cpp +#define SCOPY_NEW_TOOLMENUENTRY(id, name, icon) +// Creates: new ToolMenuEntry(id, name, icon, this->m_name, this->m_param, this) +``` + +Key properties: `id`, `name`, `icon`, `visible`, `enabled`, `running`, `attached`, `detachable`, `runEnabled`, `runBtnVisible`. + +In `onConnect()`, each tool is enabled and given its widget: +```cpp +toolList[i]->setEnabled(true); +toolList[i]->setTool(instrumentWidget); +``` + +## MessageBroker (Pub/Sub Singleton) + +```cpp +// Subscribe +MessageBroker::GetInstance()->subscribe(this, "topic_name"); + +// Publish +MessageBroker::GetInstance()->publish("topic_name", "message_data"); + +// Receive in plugin +void messageCallback(QString topic, QString message) override; +``` + +All plugins auto-subscribe to "broadcast" topic. The broker stores `QMap>` for subscriptions. + +## Preferences (Singleton) + +```cpp +// Initialize with default +Preferences::init("plugin.setting_key", defaultValue); + +// Read/Write +QVariant val = Preferences::get("plugin.setting_key"); +Preferences::set("plugin.setting_key", newValue); + +// React to changes +connect(Preferences::GetInstance(), &Preferences::preferenceChanged, + [](QString key, QVariant val) { /* handle */ }); +``` + +File-backed via QSettings. Call `save()`/`load()` for persistence. + +## IIOWidgetBuilder (Fluent Builder) + +```cpp +IIOWidgetBuilder builder(parentWidget); +auto widget = builder + .device(iio_device) + .channel(iio_channel) + .attribute("voltage") + .uiStrategy(IIOWidgetBuilder::RangeUi) + .compactMode(true) + .group(widgetGroup) + .buildSingle(); +``` + +**UI Strategies:** `EditableUi`, `ComboUi`, `SwitchUi`, `RangeUi`, `CheckBoxUi`, `TemperatureUi` +**Data Strategies:** `AttrData`, `TriggerData`, `DeviceAttrData`, `ContextAttrData` + +Priority: Channel > Device > Context (most specific wins). + +## Async Patterns + +**CyclicalTask** — periodic thread execution: +```cpp +CyclicalTask *ct = new CyclicalTask(myThread, this); +ct->start(5000); // Execute every 5 seconds +ct->stop(); +``` + +**PingTask** — device connectivity check (subclass and implement `ping()`): +```cpp +class MyPingTask : public PingTask { + bool ping() override { /* return true if device alive */ } +}; +// Signals: pingSuccess(), pingFailed(), connectionLost(), forceDisconnect() +``` + +## DeviceFactory + +```cpp +// Single static method — creates DeviceImpl with all compatible plugins +DeviceImpl *device = DeviceFactory::build(param, category, parent); +``` + +## ApiObject (JS Test Automation Base) + +```cpp +class MyPluginApi : public ApiObject { + Q_OBJECT + friend class MyPlugin; +public: + Q_INVOKABLE QString getValue(); + Q_INVOKABLE void setValue(const QString &val); +private: + MyPlugin *m_plugin = nullptr; +}; +``` + +Register in `onConnect()`: `ScopyJS::GetInstance()->registerApi(m_api)` +Delete at start of `onDisconnect()`: `delete m_api; m_api = nullptr;` diff --git a/tools/scopy_dev_plugin/skills/scopy-component-relationships/SKILL.md b/tools/scopy_dev_plugin/skills/scopy-component-relationships/SKILL.md new file mode 100644 index 0000000000..c908637429 --- /dev/null +++ b/tools/scopy_dev_plugin/skills/scopy-component-relationships/SKILL.md @@ -0,0 +1,170 @@ +--- +name: scopy-component-relationships +description: How Scopy libraries depend on each other, plugin commonalities, MessageBroker topics, shared widgets, style system flow, and build system relationships. Loaded when determining component interactions or change impact. +--- + +# Scopy Component Relationships + +## Library Dependency Graph + +``` + ┌──────────────┐ + │ scopy-core │ + └──────┬───────┘ + ┌───────────────┼───────────────────┐ + │ │ │ + ┌──────▼───────┐ ┌─────▼──────┐ ┌──────────▼──────────┐ + │scopy-pluginbase│ │ scopy-gui │ │ scopy-pkg-manager │ + └──────┬───────┘ └─────┬──────┘ └─────────────────────┘ + │ │ + ┌──────▼───────────────▼──────┐ + │ scopy-common │ + └──────┬──────────────────────┘ + │ + ┌──────▼───────┐ ┌────────────────────┐ + │ scopyiioutil │◄───│ scopy-iio-widgets │ + └──────────────┘ └────────────────────┘ + │ + ┌─────▼──────┐ + │scopy-gr-util│ + └────────────┘ +``` + +**Detailed link dependencies:** + +| Library | Links Against | +|---------|--------------| +| `scopy-common` | Qt Core/Widgets/Concurrent | +| `scopyiioutil` | Qt Widgets, libiio, libserialport | +| `scopy-gui` | scopy-common, scopy-pluginbase, QWT, Boost, Qt Widgets/Xml/Svg | +| `scopy-gr-util` | scopy-iioutil, scopy-gui, scopy-iio-widgets, Gnuradio (runtime/analog/blocks/fft/filter/pmt/iio), Genalyzer | +| `scopy-pluginbase` | scopy-common, scopyiioutil, Qt Core/Widgets/Concurrent/Qml, libiio | +| `scopy-iio-widgets` | scopy-gui, scopyiioutil, libiio, Qt Core/Widgets | +| `scopy-pkg-manager` | Qt Core | +| `scopy-core` | all above, Python3, libsigrokdecode, Qt Core/Widgets/Concurrent/Network | + +## Plugin Pattern Families + +### Device Plugins (hardware-specific) +**Packages:** ad936x, ad9371, adrv9002, adrv9009, apollo-ad9084, cn0511, daq2, fmcomms11, swiot, pqmon, imu, rfpowermeter + +**Common patterns:** +- `compatible()` checks IIO context for specific device names +- Use IIOWidgetBuilder extensively for attribute controls +- Create instrument/tool classes per device feature +- Often have gain widgets, frequency controls, calibration sections +- Use CyclicalTask/PingTask for device monitoring +- API class exposes Q_INVOKABLE methods for test automation + +### Generic Plugins +**Package:** generic-plugins +**Plugins:** ADC, DAC, Datalogger, Debugger, Regmap, JESD Status + +**Common patterns:** +- Work with any IIO device (not device-specific compatible()) +- ADC/DAC use GNU Radio pipeline (gr-util dependency) +- Debugger/Regmap are register-level tools +- Datalogger handles data recording across devices + +### Utility Plugins +**Package:** extproc (external processor), test-plugins + +**Patterns:** +- extproc: External process management, plot management +- test-plugins: Development/testing utilities (default OFF) + +## MessageBroker Topics + +The MessageBroker is a singleton pub/sub system. All plugins auto-subscribe to "broadcast". + +**Known topic conventions:** +- Topic names typically match plugin class names (e.g., "TestPlugin", "TestPlugin2") +- "broadcast" — default topic, all plugins receive +- Device-specific topics for cross-plugin coordination + +**Usage pattern:** +```cpp +// Publisher plugin +MessageBroker::GetInstance()->publish("MyPlugin", "calibration_complete"); + +// Subscriber plugin (in constructor or init) +MessageBroker::GetInstance()->subscribe(this, "MyPlugin"); + +// Receive +void messageCallback(QString topic, QString message) override { + if(topic == "MyPlugin" && message == "calibration_complete") { /* react */ } +} +``` + +## Shared IIOWidget Patterns + +IIOWidgetBuilder is used across most device plugins. Common widget configurations: + +| Widget Type | Use Case | Plugins Using It | +|-------------|----------|-----------------| +| `RangeUi` | Numeric attributes (frequency, gain) | ad936x, adrv9002, adrv9009, generic ADC/DAC | +| `ComboUi` | Enumerated attributes (mode, filter) | ad936x, adrv9002, swiot, generic | +| `CheckBoxUi` | Boolean attributes (enable/disable) | swiot, pqmon | +| `EditableUi` | Free-form text attributes | debugger, regmap | +| `TemperatureUi` | Temperature with thresholds | imu, rfpowermeter | + +**IIOWidgetGroup** — groups widgets for batch read/write operations. Most plugins create one group per tool/section. + +## Style System Flow + +``` +JSON theme files → Style::getAttribute() / Style::getColor() + → Style::setStyle(widget, property) + → Style::setBackgroundColor(widget, color) +``` + +**Key theme color categories:** + +| Category | Values | Purpose | +|----------|--------|---------| +| Background | `background_primary`, `background_subtle`, `background_secondary`, `background_plot` | Container backgrounds | +| Content | `content_default`, `content_subtle`, `content_silent`, `content_inverse` | Text and icons | +| Status | `content_success`, `content_error`, `content_busy` | Status indicators | +| Interactive | `interactive_primary_*`, `interactive_subtle_*`, `interactive_secondary_*` | Buttons, controls (idle/hover/pressed/disabled) | +| Special | `interactive_accent_idle`, `danger_default`, `interactive_focus` | Accent and danger states | + +**Common style properties:** +```cpp +Style::setStyle(widget, style::properties::label::menuBig); +Style::setStyle(widget, style::properties::widget::border_interactive); +Style::setStyle(widget, style::properties::widget::basicBackground, true, true); +Style::setBackgroundColor(widget, json::theme::background_primary); +``` + +## Build System Relationships + +**Package enable flags:** +- `ENABLE_PACKAGE_` — uppercase name with dashes preserved +- `ENABLE_ALL_PACKAGES=ON` — enables everything +- Default ON for all except: `TEST-PLUGINS` (OFF), `EXTPROC` (OFF) + +**Plugin enable flags (within a package):** +- `ENABLE_PLUGIN_` — individual plugin control +- Defined by `add_plugins()` function in PackageUtils.cmake + +**Available packages (16 total):** +ad936x, ad9371, adrv9002, adrv9009, apollo-ad9084, cn0511, daq2, extproc, fmcomms11, generic-plugins, imu, m2k, pqmon, rfpowermeter, swiot, test-plugins + +## Cross-Cutting Concerns + +### Settings Persistence +- Plugin-level: `saveSettings(QSettings&)` / `loadSettings(QSettings&)` +- Global: `Preferences::get/set()` singleton +- Both backed by QSettings (INI file format) + +### Device Connection State +- DeviceImpl manages plugin lifecycle +- `m_connectedPlugins` tracks which plugins are active +- PingTask monitors device health +- `connectionLost()` signal triggers reconnection/warning UI + +### ScopyJS (JavaScript Engine) +- Enabled by default (`ENABLE_SCOPYJS=ON`) +- API objects registered via `ScopyJS::GetInstance()->registerApi()` +- Used for test automation and scripting +- Each plugin can expose one API object diff --git a/tools/scopy_dev_plugin/skills/scopy-decision-frameworks/SKILL.md b/tools/scopy_dev_plugin/skills/scopy-decision-frameworks/SKILL.md new file mode 100644 index 0000000000..8650571c51 --- /dev/null +++ b/tools/scopy_dev_plugin/skills/scopy-decision-frameworks/SKILL.md @@ -0,0 +1,177 @@ +--- +name: scopy-decision-frameworks +description: Decision trees for common Scopy architectural choices - plugin vs core, tool vs section, widget type selection, sync vs async, GNU Radio vs direct, package organization, and API exposure. Loaded when making design decisions. +--- + +# Scopy Decision Frameworks + +## Plugin vs Core Library + +``` +Is this feature device-specific? +├── YES → Plugin (in the device's package) +└── NO + ├── Is it used by 3+ plugins? + │ ├── YES → Core library (common, gui, iioutil, or pluginbase) + │ └── NO + │ ├── Is it optional/removable? + │ │ ├── YES → Plugin (in generic-plugins package) + │ │ └── NO → Core library + │ └── Is it UI-only? + │ ├── YES → gui library + │ └── NO → common or iioutil +``` + +**Guidelines:** +- If it touches IIO directly → `iioutil` or `iio-widgets` +- If it's a reusable Qt widget → `gui` +- If it's plugin infrastructure → `pluginbase` +- If it manages packages → `pkg-manager` +- If none of the above → `common` + +## New Package vs Extend Existing + +``` +Does this support a new device family? +├── YES → New package under packages/ +└── NO + ├── Does the target device already have a package? + │ ├── YES → Add plugin to existing package + │ └── NO + │ ├── Is it a reference design using existing devices? + │ │ ├── YES → New package (like cn0511, daq2, fmcomms11) + │ │ └── NO → generic-plugins package + │ └── Is it cross-device utility? + │ └── YES → generic-plugins package +``` + +## Tool vs Section + +``` +Does this feature have its own independent workflow? +├── YES → New tool (new ToolMenuEntry in loadToolList()) +│ User sees it as a separate menu item +└── NO + ├── Is it part of an existing tool's workflow? + │ ├── YES → New section in existing tool + │ │ (MenuSectionCollapseWidget or tab) + │ └── NO + │ ├── Is it configuration/settings? + │ │ ├── YES → Preferences page (loadPreferencesPage()) + │ │ └── NO → New tool + │ └── Is it a one-time action? + │ ├── YES → Button or menu action in existing tool + │ └── NO → New tool +``` + +## IIOWidget vs Custom Widget + +``` +Does it map to a single IIO attribute? +├── YES +│ ├── Enumerated values? → IIOWidgetBuilder::ComboUi +│ ├── Numeric range? → IIOWidgetBuilder::RangeUi +│ ├── Boolean on/off? → IIOWidgetBuilder::CheckBoxUi or SwitchUi +│ ├── Free-form text? → IIOWidgetBuilder::EditableUi +│ ├── Temperature with thresholds? → IIOWidgetBuilder::TemperatureUi +│ └── Read-only status? → IIOWidgetBuilder with read-only pattern + timer polling +└── NO + ├── Multi-attribute interaction? → Custom QWidget + │ (e.g., gain + frequency coupled control) + ├── Complex visualization? → Custom QWidget with QWT plots + ├── File selection/dialog? → Custom QWidget + └── No IIO attribute at all? → Standard Qt widget +``` + +**IIOWidgetBuilder decision sub-tree:** +``` +Has available-attribute (enum options)? +├── YES → Use .optionsAttribute("attr_available") with ComboUi +└── NO + ├── Has numeric range? + │ ├── Range from optionsAttribute → .optionsAttribute() with RangeUi + │ └── Hardcoded range → .optionsValues("min max step") with RangeUi + └── No constraints → EditableUi (accepts any string) +``` + +## Sync vs Async IIO Access + +``` +What's the access pattern? +├── One-time read at startup → Direct iio_*_attr_read() in onConnect() +├── Periodic polling (device status) → CyclicalTask +│ └── Set period based on data rate needs (default 5000ms) +├── Connection health monitoring → PingTask subclass +│ └── Implement ping() to check device alive +├── User-triggered read/write → IIOWidget with read()/writeAsync() +│ └── Group with IIOWidgetGroup for batch operations +├── Continuous data streaming → GNU Radio pipeline (gr-util) +└── Event-driven updates → MessageBroker subscription +``` + +## GNU Radio vs Direct Data Processing + +``` +Is this continuous data streaming? +├── YES +│ ├── Needs signal processing (FFT, filtering, decimation)? +│ │ ├── YES → GNU Radio pipeline with gr-util +│ │ └── NO → Direct IIO buffer reads +│ ├── Needs real-time plotting? +│ │ ├── YES → GNU Radio → QWT plot sink +│ │ └── NO → Direct IIO → custom processing +│ └── Multiple channels with different processing? +│ └── YES → GNU Radio flowgraph (natural multi-path support) +└── NO + ├── Single attribute read/write → IIOWidget or direct IIO call + ├── Batch attribute operations → IIOWidgetGroup + └── Register-level access → Direct IIO device attribute read/write +``` + +## API Exposure Decision + +``` +Does this feature need automated testing? +├── YES → Create *_api.h / *_api.cpp +│ ├── Inherit from ApiObject +│ ├── Q_INVOKABLE on all public methods +│ ├── friend class in plugin header +│ ├── Register with ScopyJS in onConnect() +│ └── Delete at start of onDisconnect() +└── NO + ├── Is it UI-only with no testable state? + │ └── YES → No API needed + ├── Might it need scripting access later? + │ └── YES → Create API now (cheaper than retrofitting) + └── Is it infrastructure/internal? + └── YES → No API needed +``` + +## Testing Strategy Decision + +``` +What type of feature is this? +├── Core library change → Qt unit tests in library's test/ dir +├── Plugin with IIO attributes +│ ├── Unit tests → Qt Test (mock IIO context if possible) +│ ├── Integration tests → JS HITL tests (claude_scopy_dev_plugin branch) +│ ├── Manual tests → RST test docs with UIDs and RBP levels +│ └── API class → Required for JS automation +├── UI-only change +│ ├── Visual tests → JS VisualTests.js with supervisedCheck() +│ └── Manual tests → RST test docs (Category C) +└── Build/CI change → CI pipeline validation +``` + +## Communication Pattern Decision + +``` +Who needs to know about this event? +├── Same plugin only → Qt signals/slots (direct connection) +├── Other plugins need to react +│ ├── Known recipients → MessageBroker with specific topic +│ └── Broadcast to all → MessageBroker with "broadcast" topic +├── Core needs to react → Plugin signals (connectDevice, disconnectDevice, etc.) +├── UI needs to update → Qt signals/slots + property binding +└── External tools need access → ScopyJS API registration +``` diff --git a/tools/scopy_dev_plugin/skills/scopy-tools-inventory/SKILL.md b/tools/scopy_dev_plugin/skills/scopy-tools-inventory/SKILL.md new file mode 100644 index 0000000000..9adfcd136d --- /dev/null +++ b/tools/scopy_dev_plugin/skills/scopy-tools-inventory/SKILL.md @@ -0,0 +1,135 @@ +--- +name: scopy-tools-inventory +description: Catalog of all Scopy development tools including package generator, testing tools, CI scripts, format/license scripts, and dev plugin commands. Loaded when analyzing what tools exist for a task. +--- + +# Scopy Tools Inventory + +## Package Generator + +**Location:** `tools/packagegenerator/` +**Purpose:** Generate complete package/plugin scaffolding from JSON configuration. + +**Usage:** +```bash +cd tools/packagegenerator +pip install -r requirements.txt +./package_generator.py --all # Generate complete package +./package_generator.py -p /path/to/plugin.json # Generate plugin only +./package_generator.py --init # Initialize git submodule +./package_generator.py --style # Add style templates +./package_generator.py --translation # Add translation templates +./package_generator.py -a --src /path --dest /path # Archive packages +``` + +**Input files:** +- `pkg.json` — Package metadata (id, title, description, version, category) +- `plugin.json` — Plugin structure definition with 14 fields: + - `baseplugin`, `plugin_name`, `plugin_display_name`, `plugin_description` + - `class_name`, `namespace`, `device_category` + - `tools[]` — array of {id, tool_name, file_name, class_name, namespace} + - `cmakelists` — {cmake_min_required, cxx_standard, enable_testing} + - `style`, `test`, `resources`, `doc`, `pdk` + +**When to use:** Creating a brand new package or plugin from scratch. Not for modifying existing plugins. + +## Testing Tools + +### Manual Test Environment +**Location:** `tools/testing/` + +```bash +python3 setup_test_environment.py v3.0.0 --rbp P0 --new-since v2.5.0 +``` + +- `setup_test_environment.py` — Create filtered test environments by version/component/priority +- `parseTestResults.py` — Generate CSV templates from RST test documentation +- `rst_parser.py` — Parse RST test files +- `file_filters.py` — Component and priority filtering + +### JS Test Automation +**Location:** `js/testAutomations/` + +``` +testAutomations/ +├── common/testFramework.js # Base test API +├── core/ # Core tests +├── generic-plugins/ # Generic plugin tests (adc/, dac/, etc.) +├── m2k/ # M2K-specific tests +├── ad936x/, adrv9002/, ... # Device-specific tests +``` + +- `DocTests.js` — Category A: fully automatable tests +- `VisualTests.js` — Category B: supervised visual checks +- Test names must match RST UIDs exactly +- Every setter followed by `msleep(500)` for hardware settle +- Save/restore original values in all code paths + +### JS Hardware-in-the-Loop Testing +**Branch:** `claude_scopy_dev_plugin` (not yet in main) +**Purpose:** Automated testing with real hardware via JS scripts. + +### Unit Tests +- Each library/plugin has `test/` subdirectory with Qt Test-based tests +- Enable with `-DENABLE_TESTING=ON` +- Run: `cd build && ctest -R ` + +## Code Quality Tools + +### Format Script +**Location:** `tools/format.sh` +- Uses clang-format for C++ files +- Uses cmake-format for CMake files +- Run before every commit + +### License Script +**Location:** `tools/license.sh` +- Adds GPL license headers to source files +- Run before every commit + +### Dev Plugin Quality Commands +- `/scopy_dev_plugin:check-code-quality ` — Static code quality analysis +- `/scopy_dev_plugin:verify-package ` — CI pre-flight validation +- `/scopy_dev_plugin:validate-api ` — Validate API class (checks A1-A7) +- `/scopy_dev_plugin:validate-automated-tests ` — Validate JS tests (checks T1-T7) + +## Code Generation Commands + +- `/scopy_dev_plugin:create-api ` — Generate Q_INVOKABLE API class for JS automation +- `/scopy_dev_plugin:create-docs ` — Generate RST user-guide documentation +- `/scopy_dev_plugin:create-test-docs ` — Generate RST test case documentation +- `/scopy_dev_plugin:create-automated-tests ` — Create JS automated test scripts +- `/scopy_dev_plugin:create-whatsnew ` — Generate What's New HTML + +## CI Scripts + +**Location:** `ci/` + +Platform-specific build scripts: +- `ci/ubuntu/` — Ubuntu/Linux build and packaging +- `ci/windows/` — Windows build with MSVC +- `ci/macOS/` — macOS build +- `ci/arm/` — ARM cross-compilation (armv7) +- `ci/android/` — Android build + +Each directory contains scripts for dependency installation, build configuration, and packaging. + +## MCP Server + +**Location:** `tools/scopy-mcp-server/` +**Purpose:** External tooling integration via Model Context Protocol. + +## Build System + +```bash +mkdir build && cd build +cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo +make -j$(nproc) + +# Key flags +-DENABLE_ALL_PACKAGES=ON # All packages +-DENABLE_PACKAGE_=ON # Specific package (uppercase) +-DENABLE_TESTING=ON # Unit tests +-DENABLE_AUTOMATED_TESTS=ON # JS automated tests (ctest) +-DSCOPY_DEV_MODE=ON # Dev mode (clears cache on reconfigure) +``` From d56b8a3696a5ea35d6def944c8a723093555bb2a Mon Sep 17 00:00:00 2001 From: IonutMuthi Date: Wed, 22 Apr 2026 11:59:11 +0300 Subject: [PATCH 2/2] claude: update plugin README Signed-off-by: IonutMuthi --- tools/scopy_dev_plugin/README.md | 40 +++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/tools/scopy_dev_plugin/README.md b/tools/scopy_dev_plugin/README.md index 1995ac3e9e..3e2e32005f 100644 --- a/tools/scopy_dev_plugin/README.md +++ b/tools/scopy_dev_plugin/README.md @@ -29,6 +29,29 @@ Both must be on your `PATH`. On Ubuntu: `sudo apt install clang-format` and `pip ## Slash Commands +### Task Refinement Pipeline + +Turn vague development ideas into concrete, actionable designs. These two commands form a pipeline — use `/clarify-task` to refine a vague idea, then `/design-task` to produce a full design document. Each command is independently usable. + +| Command | Description | +|---------|-------------| +| `/scopy_dev_plugin:clarify-task ` | Ask clarifying questions, explore code, produce a structured task brief | +| `/scopy_dev_plugin:design-task ` | Analyze architecture, propose approaches, produce a full design document | + +**Recommended model:** Opus — both commands perform deep codebase exploration and complex architectural reasoning. + +**Example workflow:** +``` +/scopy_dev_plugin:clarify-task add spectrum analyzer to ADC plugin + → answers questions, explores code → task brief + +/scopy_dev_plugin:design-task + → proposes 2-3 approaches → detailed design doc + → optionally saved to docs/design/ +``` + +### Code Generation & Documentation + | Command | Description | |---------|-------------| | `/scopy_dev_plugin:create-api ` | Generate JavaScript API class for test automation | @@ -36,6 +59,11 @@ Both must be on your `PATH`. On Ubuntu: `sudo apt install clang-format` and `pip | `/scopy_dev_plugin:create-test-docs ` | Generate RST test case documentation | | `/scopy_dev_plugin:create-automated-tests ` | Create JS automated test scripts | | `/scopy_dev_plugin:create-whatsnew ` | Generate What's New HTML page | + +### Quality & Validation + +| Command | Description | +|---------|-------------| | `/scopy_dev_plugin:check-code-quality ` | Static code quality analysis | | `/scopy_dev_plugin:verify-package ` | CI pre-flight validation (format + license) | | `/scopy_dev_plugin:validate-api ` | Validate API class implementation (checks A1–A7) | @@ -45,12 +73,22 @@ Both must be on your `PATH`. On Ubuntu: `sudo apt install clang-format` and `pip These skills are loaded automatically when relevant context is detected: +### Plugin Development - **iiowidget-patterns** — How to create IIOWidgets using IIOWidgetBuilder - **scopy-style-rules** — Theme system, Style::setStyle, background colors - **scopy-plugin-patterns** — Plugin lifecycle, ToolTemplate, refresh buttons +- **scopy-api-patterns** — API class structure and Q_INVOKABLE patterns + +### Documentation & Testing - **scopy-doc-format** — RST documentation conventions - **scopy-test-format** — Test case UID and RBP conventions -- **scopy-api-patterns** — API class structure and Q_INVOKABLE patterns + +### Task Refinement (loaded by clarify-task and design-task commands) +- **scopy-architecture-knowledge** — Plugin lifecycle, library dependencies, build system, key design patterns +- **scopy-tools-inventory** — Catalog of all dev tools (package generator, CI, testing, format scripts) +- **scopy-component-relationships** — Library dependency graph, plugin families, style system, build flags +- **scopy-decision-frameworks** — Decision trees for plugin vs core, widget type, sync vs async, API exposure +- **external-research** — Guidelines for researching external solutions (Context7, ADI docs, web search) ## Hooks