spec-kit: specify, clarify, and plan for "Add plugin example implementations" (feature 002)

package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/anikitenko/fdo-sdk.git"
   },
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "SDK for FlexDevOPs (FDO) application modules",
   "keywords": [
     "fdo",
@@ -26,7 +26,7 @@
   "files": [
     "dist"
   ],
-    "scripts": {
+  "scripts": {
     "build": "webpack --config webpack.config.cjs",
     "build:types": "tsc --emitDeclarationOnly",
     "test": "jest",

specs/002-plugin-example-implementations/clarify.md

@@ -0,0 +1,207 @@
+# Clarification Questions: Add Plugin Example Implementations
+
+**Feature**: Add Plugin Example Implementations  
+**Branch**: `002-plugin-example-implementations`  
+**Date**: 2025-10-27  
+**Status**: Clarification Phase
+
+## Purpose
+
+This document identifies underspecified areas in the feature specification that need clarification before proceeding to implementation planning. Each question is categorized by priority and impact on implementation.
+
+---
+
+## Critical Clarifications (Must Resolve Before Planning)
+
+### C1: Example File Naming and Organization
+
+**Question**: How should the example files be named and organized within the examples/ directory?
+
+**Current State**: The specification mentions "at least 4 complete, working plugin examples" but doesn't specify naming conventions or directory structure.
+
+**Options**:
+1. Flat structure with descriptive names (e.g., `basic-plugin.ts`, `interactive-plugin.ts`, `persistence-plugin.ts`, `advanced-plugin.ts`)
+2. Numbered structure matching priority (e.g., `01-basic-plugin.ts`, `02-interactive-plugin.ts`, etc.)
+3. Categorized subdirectories (e.g., `examples/basic/`, `examples/intermediate/`, `examples/advanced/`)
+4. Use case-based names (e.g., `todo-list-plugin.ts`, `note-taking-plugin.ts`, `settings-panel-plugin.ts`)
+
+**Recommendation**: Use numbered structure with descriptive names (Option 2) for clear progression, combined with use case-based naming (Option 4) for relatability. Example: `01-basic-hello-world.ts`, `02-interactive-todo-list.ts`, `03-persistent-notes.ts`, `04-advanced-settings-panel.ts`
+
+**Impact**: High - affects file structure and documentation references
+
+---
+
+### C2: Example Plugin Realistic Use Cases
+
+**Question**: What specific realistic use cases should each example demonstrate?
+
+**Current State**: FR-014 mentions "realistic use cases that developers can relate to (e.g., todo list, note-taking, settings panel)" but doesn't assign specific use cases to each example.
+
+**Proposed Mapping**:
+- **Basic Example (P1)**: "Hello World" plugin - displays a simple greeting with plugin metadata
+- **Interactive Example (P2)**: Todo List plugin - demonstrates buttons, inputs, and state management
+- **Persistence Example (P3)**: Note-Taking plugin - demonstrates saving and loading notes across sessions
+- **Advanced Example (P4)**: Settings Panel plugin - demonstrates quick actions, side panel, and complex UI
+
+**Rationale**: These use cases are universally understood, progressively complex, and demonstrate real-world plugin patterns.
+
+**Impact**: High - defines the scope and complexity of each example
+
+---
+
+### C3: Documentation Location and Format
+
+**Question**: Where should example documentation be placed, and in what format?
+
+**Current State**: FR-005 mentions "README or header comment" but doesn't specify which approach to use or if both should be used.
+
+**Options**:
+1. Header comments only (inline documentation)
+2. Separate README.md in examples/ directory
+3. Both header comments and README.md
+4. Individual README.md for each example in subdirectories
+
+**Recommendation**: Use both (Option 3):
+- Comprehensive header comments in each example file (for developers reading the code)
+- Single `examples/README.md` that provides overview, lists all examples, and explains progression
+- Update main SDK README.md to reference the examples
+
+**Impact**: Medium - affects documentation structure and developer experience
+
+---
+
+## Important Clarifications (Should Resolve Before Implementation)
+
+### C4: Example Code Style and Patterns
+
+**Question**: Should examples follow a specific code style or pattern that differs from production code for educational purposes?
+
+**Current State**: FR-006 states examples must follow "same code quality standards as the SDK itself" but doesn't clarify if examples should be more verbose/explicit for educational purposes.
+
+**Considerations**:
+- Should examples use more explicit typing even when inference would work?
+- Should examples include more error handling than strictly necessary to demonstrate best practices?
+- Should examples use longer, more descriptive variable names for clarity?
+- Should examples avoid advanced TypeScript features to remain accessible?
+
+**Recommendation**: Examples should be slightly more verbose and explicit than production code:
+- Use explicit type annotations even when inference works
+- Include comprehensive error handling with explanatory log messages
+- Use descriptive variable names (e.g., `todoItemText` instead of `text`)
+- Add comments explaining "why" not just "what"
+- Avoid advanced TypeScript features unless demonstrating them is the example's purpose
+
+**Impact**: Medium - affects code readability and educational value
+
+---
+
+### C5: Testing Strategy for Examples
+
+**Question**: How should examples be tested to ensure they remain functional as the SDK evolves?
+
+**Current State**: SC-002 states "Each example runs successfully in the FDO application without errors" but doesn't specify how this will be verified.
+
+**Options**:
+1. Manual testing only (run each example and verify behavior)
+2. Automated unit tests for example plugins
+3. Integration tests that load examples in a test FDO environment
+4. CI/CD pipeline that builds and validates examples
+5. Combination of manual and automated testing
+
+**Recommendation**: Use combination approach (Option 5):
+- Add automated build validation in CI/CD to ensure examples compile without errors
+- Include examples in the existing test suite to verify they can be instantiated
+- Document manual testing steps in examples/README.md
+- Consider adding integration tests in future if FDO test environment becomes available
+
+**Impact**: Medium - affects long-term maintainability and quality assurance
+
+---
+
+### C6: Example Plugin Metadata Standards
+
+**Question**: What metadata standards should examples follow to avoid conflicts and confusion?
+
+**Current State**: FR-012 requires "unique, descriptive metadata" but doesn't specify conventions.
+
+**Considerations**:
+- Should all examples use a common author (e.g., "FDO SDK Team")?
+- Should example names include "Example" suffix (e.g., "Todo List Example Plugin")?
+- Should versions all start at 1.0.0 or follow SDK version?
+- Should descriptions follow a template format?
+
+**Recommendation**:
+- Author: "FDO SDK Team" (consistent across all examples)
+- Name: Include "Example" suffix (e.g., "Todo List Example")
+- Version: Start at 1.0.0 (independent of SDK version)
+- Description: Follow template: "Example plugin demonstrating [features]. Shows how to [key learning points]."
+- Icon: Use consistent placeholder icons or simple emoji-based icons
+
+**Impact**: Low - affects metadata consistency but not functionality
+
+---
+
+## Nice-to-Have Clarifications (Can Resolve During Implementation)
+
+### C7: Example Complexity and Length
+
+**Question**: What is the target length/complexity for each example to balance completeness with readability?
+
+**Current State**: No specific guidance on example size.
+
+**Recommendation**:
+- Basic example: 50-100 lines of code (excluding comments)
+- Interactive example: 100-200 lines of code
+- Persistence example: 150-250 lines of code
+- Advanced example: 200-300 lines of code
+- Aim for 30-40% comment-to-code ratio (per SC-004)
+
+**Impact**: Low - provides guidance but can be adjusted during implementation
+
+---
+
+### C8: Example Styling and Visual Design
+
+**Question**: Should examples include styled UI or use minimal/default styling?
+
+**Current State**: FR-015 requires "proper CSS-in-JS usage" but doesn't specify styling expectations.
+
+**Options**:
+1. Minimal styling (focus on functionality)
+2. Basic styling (clean but simple)
+3. Polished styling (production-ready appearance)
+
+**Recommendation**: Use basic styling (Option 2):
+- Examples should look clean and professional but not overly designed
+- Focus on demonstrating CSS-in-JS patterns rather than visual design
+- Use simple color schemes and layouts
+- Include comments explaining styling choices
+
+**Impact**: Low - affects visual appearance but not core functionality
+
+---
+
+## Decisions Made
+
+Based on the clarifications above, the following decisions are recommended for the planning phase:
+
+1. **File Structure**: Use numbered, use-case-based naming in flat examples/ directory
+2. **Use Cases**: Hello World (basic), Todo List (interactive), Note-Taking (persistence), Settings Panel (advanced)
+3. **Documentation**: Both inline comments and examples/README.md, plus main README update
+4. **Code Style**: Slightly more verbose and explicit than production code for educational purposes
+5. **Testing**: Automated build validation + manual testing documentation
+6. **Metadata**: Consistent standards with "FDO SDK Team" author and "Example" suffix in names
+7. **Complexity**: Target 50-300 lines per example with 30-40% comment ratio
+8. **Styling**: Basic, clean styling that demonstrates CSS-in-JS without over-designing
+
+---
+
+## Open Questions for User/Stakeholder
+
+None at this time. All critical and important clarifications have been addressed with recommendations. If any decisions need to be changed, they can be adjusted during the planning phase.
+
+---
+
+## Next Steps
+
+With these clarifications in place, we can proceed to the **speckit.plan** phase to create a detailed technical implementation plan.