x-ipe 1.0.24__py3-none-any.whl → 1.0.25__py3-none-any.whl

x_ipe/resources/skills/task-type-feature-refinement/references/specification-writing-guide.md

@@ -0,0 +1,267 @@
+# Feature Specification Writing Guide
+
+This guide provides detailed templates, examples, and best practices for writing feature specifications.
+
+---
+
+## Specification Section Templates
+
+### Overview Section
+
+Write 2-3 paragraphs covering:
+1. **What** - What this feature does
+2. **Why** - Why it's needed
+3. **Who** - Who will use it
+
+### User Stories Template
+
+```markdown
+As a [user type], I want to [action/goal], so that [benefit/value].
+```
+
+**Examples:**
+- As a **customer**, I want to **save items to my cart**, so that **I can purchase them later**.
+- As an **admin**, I want to **view all user orders**, so that **I can track sales and resolve issues**.
+- As a **developer**, I want to **access API documentation**, so that **I can integrate with the service**.
+- As a **support agent**, I want to **search customer tickets**, so that **I can quickly find and resolve issues**.
+
+### Acceptance Criteria Template
+
+Format: `- [ ] Criterion: [Specific, measurable condition]`
+
+**Good Examples:**
+- [ ] User can add up to 50 items to cart
+- [ ] Cart total updates within 200ms of item addition
+- [ ] Error message displays when stock is insufficient
+- [ ] Session persists for 24 hours of inactivity
+
+**Bad Examples (avoid):**
+- [ ] Cart works correctly (too vague)
+- [ ] System is fast (not measurable)
+- [ ] User has good experience (subjective)
+
+---
+
+## Functional Requirements Template
+
+### FR-N: [Requirement Name]
+
+**Description:** [What the system must do]
+
+**Details:**
+- Input: [What data is provided]
+- Process: [What happens]
+- Output: [What result is produced]
+
+**Example - FR-1: Add to Cart**
+
+**Description:** System must allow users to add products to their shopping cart.
+
+**Details:**
+- Input: Product ID, quantity (1-99)
+- Process: Validate stock availability, add to cart, recalculate total
+- Output: Updated cart with new item, total price displayed
+
+---
+
+## Non-Functional Requirements Templates
+
+### NFR-1: Performance
+
+- Response time: [X seconds/milliseconds]
+- Throughput: [X requests per second]
+- Concurrent users: [X users]
+
+**Example:**
+- Response time: < 200ms for cart operations
+- Throughput: 1000 add-to-cart requests per second
+- Concurrent users: 10,000 simultaneous sessions
+
+### NFR-2: Security
+
+- Authentication required: [Yes/No]
+- Authorization level: [Role/permission required]
+- Data encryption: [What data, how encrypted]
+
+**Example:**
+- Authentication required: Yes (JWT token)
+- Authorization level: Registered customer or higher
+- Data encryption: Credit card data encrypted with AES-256
+
+### NFR-3: Scalability
+
+- Expected growth: [User/data growth projections]
+- Scaling strategy: [Horizontal/vertical]
+
+---
+
+## UI/UX Requirements Template
+
+**Wireframes/Mockups:** [Link or embed]
+
+**User Flows:**
+1. User navigates to [page/screen]
+2. User performs [action]
+3. System displays [result]
+
+**UI Elements:**
+- Button: [Label, action]
+- Form fields: [List with validation rules]
+- Error messages: [List with conditions]
+
+**Example User Flow - Checkout:**
+1. User navigates to cart page
+2. User clicks "Proceed to Checkout"
+3. System validates cart items in stock
+4. System displays shipping address form
+5. User enters address and clicks "Continue"
+6. System displays payment options
+
+---
+
+## Business Rules Template
+
+### BR-N: [Rule Name]
+
+**Rule:** [Clear statement of business rule]
+
+**Examples:**
+- Only authenticated users can add items to cart
+- Prices must be positive numbers
+- Discounts cannot exceed 90%
+- Free shipping applies to orders over $50
+- Refunds must be processed within 14 days
+
+---
+
+## Edge Cases & Constraints Template
+
+### Edge Case N: [Scenario]
+
+**Scenario:** [Describe unusual or boundary condition]  
+**Expected Behavior:** [How system should respond]
+
+**Common Edge Cases to Consider:**
+| Category | Edge Cases |
+|----------|------------|
+| User Session | Session expires during operation, multiple tabs open |
+| Data | Empty state, maximum limit reached, invalid format |
+| Network | Connection lost, slow response, timeout |
+| Concurrency | Simultaneous edits, race conditions |
+| Boundary | Min/max values, empty inputs, special characters |
+
+**Example:**
+- User session expires during checkout → Redirect to login, preserve cart
+- Database connection lost → Show error, queue for retry
+- Invalid input format → Return validation error with details
+
+---
+
+## Out of Scope Template
+
+Format: `- [What is NOT included and why/when planned]`
+
+**Examples:**
+- Social media login (only email/password for v1.0)
+- Multi-factor authentication (planned for v2.0)
+- Mobile app support (web only for v1.0)
+- International shipping (domestic only for launch)
+
+---
+
+## Dependencies Section Templates
+
+### Internal Dependencies
+
+Format: `- **FEATURE-XXX:** [Why needed, what it provides]`
+
+**Example:**
+- **FEATURE-001:** User authentication - provides user identity for cart association
+- **FEATURE-003:** Product catalog - provides product data for cart items
+
+### External Dependencies
+
+Format: `- **Name:** [Purpose, version if known]`
+
+**Example:**
+- **Stripe SDK v3.2:** Payment processing
+- **SendGrid API:** Email notifications
+- **Redis 7.0:** Session storage
+
+---
+
+## Linked Mockups Section Template
+
+```markdown
+## Linked Mockups
+
+| Mockup | Type | Path | Description |
+|--------|------|------|-------------|
+| Dashboard Main | HTML | [mockups/dashboard-v1.html](mockups/dashboard-v1.html) | Main dashboard layout |
+| Settings Panel | HTML | [mockups/settings.html](mockups/settings.html) | User settings page |
+
+> **Note:** UI/UX requirements below are derived from these mockups.
+```
+
+---
+
+## Mockup-to-Specification Mapping
+
+| Mockup Element | Specification Section |
+|----------------|----------------------|
+| Layout/Components | UI/UX Requirements → UI Elements |
+| Forms/Inputs | Functional Requirements + Validation Rules |
+| Buttons/Actions | User Stories + Acceptance Criteria |
+| Navigation | User Flows |
+| Error States | Edge Cases & Constraints |
+| Data Display | Functional Requirements → Output |
+| Loading States | Edge Cases → Empty/Loading |
+| Responsive Hints | NFR → Accessibility |
+
+---
+
+## Mockup Analysis Checklist
+
+When analyzing mockups, extract:
+
+- [ ] Layout structure and component hierarchy
+- [ ] User interaction patterns (clicks, hovers, inputs)
+- [ ] Visual design elements (colors, spacing, typography)
+- [ ] Form fields, validation rules, error states
+- [ ] Navigation flows and page transitions
+- [ ] Responsive behavior hints
+- [ ] Loading states
+- [ ] Empty states
+- [ ] Error states
+
+---
+
+## Version History Format
+
+```markdown
+## Version History
+
+| Version | Date | Description |
+|---------|------|-------------|
+| v2.0 | 01-22-2026 | Major upgrade: xterm.js, session persistence, split-pane |
+| v1.0 | 01-18-2026 | Initial specification |
+```
+
+**Rules:**
+- Maintain ONE specification file per feature
+- Add/update Version History table after the header
+- Increment version in document header (v1.0 → v2.0)
+- Update content in place with new version
+
+---
+
+## Specification Quality Checklist
+
+- [ ] All acceptance criteria are testable
+- [ ] User stories provide clear value
+- [ ] Functional requirements are complete
+- [ ] Non-functional requirements defined
+- [ ] Dependencies clearly stated
+- [ ] Edge cases identified
+- [ ] Out of scope explicitly listed
+- [ ] Mockups linked and analyzed (if applicable)

x_ipe/resources/skills/task-type-idea-mockup/SKILL.md

@@ -19,41 +19,16 @@ Create visual mockups and prototypes for refined ideas by:
 ## Important Notes
 
 ### Skill Prerequisite
-- If you HAVE NOT learned `task-execution-guideline` and `task-board-management` skill, please learn them first before executing this skill.
-- **Frontend Design Skill:** Learn `tool-frontend-design` skill if `stages.ideation.mockup.tool-frontend-design` is enabled in config.
+- Learn `task-execution-guideline` and `task-board-management` skills first.
+- Learn `tool-frontend-design` skill if enabled in config.
 
-**Important:** If Agent DO NOT have skill capability, can directly go to `.github/skills/` folder to learn skills. And SKILL.md file is the entry point to understand each skill.
+**Important:** If Agent lacks skill capability, go to `.github/skills/` folder to learn skills via SKILL.md files.
 
 ### ⚠️ UI/UX Focus Only
 
-**When generating mockups, focus ONLY on UI/UX presentation:**
+**Focus ONLY on UI/UX presentation—ignore all tech stack mentions.**
 
-| Focus On | Ignore |
-|----------|--------|
-| Visual layout and composition | Backend tech stack (Python, Node.js, etc.) |
-| User interaction patterns | Database choices (PostgreSQL, MongoDB, etc.) |
-| Navigation and flow | API implementation details |
-| Color schemes and typography | Framework specifics (React, Vue, Django, etc.) |
-| Responsive design | Infrastructure and deployment |
-| Component placement | Authentication mechanisms |
-| User experience | Server architecture |
-
-**Rationale:** Mockups are for visualizing the user experience, not technical implementation. Tech stack decisions come later during Technical Design.
-
-**Example:**
-```
-Idea mentions: "Build with React and Node.js, use PostgreSQL"
-
-Mockup should show:
-✓ How the dashboard looks
-✓ Where buttons and inputs are placed
-✓ User flow between screens
-
-Mockup should NOT include:
-✗ React component structure
-✗ API endpoint labels
-✗ Database schema hints
-```
+See [references/mockup-guidelines.md](references/mockup-guidelines.md) for detailed focus guidelines.
 
 ---
 
@@ -76,89 +51,13 @@ Mockup should NOT include:
 |-----------|---------------|-------------|
 | Auto Proceed | False | Auto-advance to next task |
 | Ideation Toolbox Meta | `{project_root}/x-ipe-docs/config/tools.json` | Config file for enabled tools |
-| Current Idea Folder | N/A | **Required from context** - path to current idea folder (e.g., `x-ipe-docs/ideas/mobile-app-idea`) |
+| Current Idea Folder | N/A | **Required from context** - path to current idea folder |
 | Extra Instructions | N/A | Additional context or requirements for mockup creation |
 
-### Extra Instructions Attribute
-
-**Purpose:** Provides additional context or requirements for the mockup creation process.
-
-**Source:** This value can be obtained from:
-1. Human input (explicit instructions provided)
-2. `x-ipe-docs/config/tools.json` → `stages.ideation.mockup._extra_instruction` field
-3. Default: N/A (no extra instructions)
-
-**Loading Logic:**
-```
-1. IF human provides explicit Extra Instructions:
-   → Use human-provided value
-
-2. ELSE IF x-ipe-docs/config/tools.json exists:
-   a. Read stages.ideation.mockup._extra_instruction field
-   b. IF field exists AND is not empty:
-      → Use value from config
-   c. ELSE:
-      → Use default: N/A
-
-3. IF Extra Instructions != N/A:
-   → Apply these instructions when identifying mockup needs
-   → Consider them when invoking mockup tools
-   → Factor them into design preferences
-   → Reference them during human review
-```
-
-**Usage:** When Extra Instructions are provided, the agent MUST incorporate them into the mockup creation workflow, particularly when designing UI elements and choosing visual styles.
-
-### Current Idea Folder Attribute
-
-**Source:** This value MUST be obtained from context:
-- From previous Ideation task output (`idea_folder` field)
-- From task board (associated idea folder)
-- From human input if not available in context
-
-**Validation:**
-```
-1. IF Current Idea Folder == N/A:
-   → Ask human: "Which idea folder should I create mockups for?"
-   → List available folders under x-ipe-docs/ideas/
-   → Wait for human selection
-
-2. IF Current Idea Folder provided:
-   → Validate folder exists
-   → Verify idea-summary-vN.md exists in folder
-   → Proceed with mockup creation
-```
-
-**Usage:**
-- All mockups are saved to `{Current Idea Folder}/mockups/`
-- Idea summary updates reference `{Current Idea Folder}/idea-summary-vN.md`
-- Output links use `{Current Idea Folder}` as base path
-
-### Ideation Toolbox Meta File
-
-**Location:** `x-ipe-docs/config/tools.json` (relative to project root)
-
-**Relevant Config Section:**
-```json
-{
-  "version": "2.0",
-  "stages": {
-    "ideation": {
-      "mockup": {
-        "tool-frontend-design": true
-      }
-    }
-  }
-}
-```
-
-**Tool Loading Rules:**
-
-1. **File exists:** Load and parse the JSON configuration
-2. **File missing:** Inform user mockup tools not configured, proceed with manual description
-3. **Tool enabled (`true`):** Invoke corresponding skill/capability
-4. **Tool disabled (`false`):** Skip the tool
-5. **Tool unavailable:** Log limitation and provide alternative
+**Attribute Details:** See [references/mockup-guidelines.md](references/mockup-guidelines.md) for:
+- Extra Instructions loading logic and usage
+- Current Idea Folder validation procedure
+- Tool configuration details and loading rules
 
 ---
 
@@ -227,34 +126,17 @@ Execute Idea Mockup by following these steps in order:
 
 ### Step 2: Load Mockup Tool Configuration
 
-**Action:** Read and parse the mockup section from ideation tools config
-
-**Default Path:** `x-ipe-docs/config/tools.json`
+**Action:** Read and parse mockup section from `x-ipe-docs/config/tools.json`
 
 ```
-1. Check if x-ipe-docs/config/tools.json exists
-2. If exists:
-   a. Parse JSON file
-   b. Extract stages.ideation.mockup section configuration
-   c. Identify enabled tools (value = true)
-   d. Extract _extra_instruction from stages.ideation.mockup section (if exists)
-3. If NOT exists:
-   a. Inform user: "No mockup tools configured"
-   b. Ask: "Proceed with manual mockup description? (Y/N)"
-4. Load Extra Instructions:
-   a. IF human provided explicit Extra Instructions → Use human value
-   b. ELSE IF _extra_instruction field exists and is not empty → Use config value
-   c. ELSE → Set Extra Instructions = N/A
-5. Log active mockup tool configuration and Extra Instructions (if any)
+1. Check if config file exists
+2. If exists: Parse JSON, extract stages.ideation.mockup section
+3. If NOT exists: Ask "Proceed with manual mockup description? (Y/N)"
+4. Load Extra Instructions (human input > config > N/A)
+5. Log active configuration
 ```
 
-**Mockup Tool Mapping:**
-
-| Config Key | Skill/Capability | What It Creates |
-|------------|------------------|-----------------|
-| `stages.ideation.mockup.tool-frontend-design` | `tool-frontend-design` skill | HTML/CSS mockups, interactive prototypes |
-| `stages.ideation.mockup.figma-mcp` | Figma MCP server | Figma design files |
-| `stages.ideation.mockup.excalidraw` | Excalidraw integration | Sketch-style wireframes |
+**Tool Mapping:** See [references/mockup-guidelines.md](references/mockup-guidelines.md) for detailed tool mapping table.
 
 **Output:** List of enabled mockup tools
 
@@ -279,31 +161,9 @@ Execute Idea Mockup by following these steps in order:
 
 **Action:** Analyze idea summary to determine what mockups to create
 
-**Analysis Questions:**
-```
-1. Does the idea describe a user interface?
-   → If yes, identify screens/pages needed
-   
-2. Does the idea mention user interactions?
-   → If yes, identify interactive elements
-   
-3. Does the idea describe a workflow?
-   → If yes, identify flow visualization needs
-   
-4. What is the primary user-facing component?
-   → Prioritize mockup for this component
-```
+**Analysis:** Identify screens/pages, interactive elements, workflow visualizations, and primary user-facing components.
 
-**Mockup Types to Consider:**
-
-| Idea Contains | Mockup Type | Priority |
-|---------------|-------------|----------|
-| Dashboard description | Dashboard layout | High |
-| Form/input mentions | Form mockup | High |
-| List/table data | Data display mockup | Medium |
-| Navigation mentions | Nav structure | Medium |
-| Charts/graphs | Data visualization | Medium |
-| Mobile mentions | Mobile-responsive mockup | High |
+**Mockup Types:** See [references/mockup-guidelines.md](references/mockup-guidelines.md) for mockup type priority table.
 
 **Output:** Prioritized list of mockups to create
 
@@ -313,104 +173,28 @@ Execute Idea Mockup by following these steps in order:
 
 **⚠️ REMINDER: Focus on UI/UX only. Ignore all tech stack mentions from idea files.**
 
-**IF `stages.ideation.mockup.tool-frontend-design: true`:**
-```
-1. Invoke `tool-frontend-design` skill
-2. Pass context:
-   - Current Idea Folder path
-   - Idea summary content (UI/UX elements only)
-   - Identified mockup needs
-   - Design preferences (if mentioned in idea)
-   - NOTE: Do NOT pass tech stack information
-3. Request HTML/CSS mockup generation
-4. Skill will create interactive prototype
-```
-
-**Tool-Frontend-Design Skill Invocation:**
-```yaml
-skill: tool-frontend-design
-context:
-  type: idea-mockup
-  idea_folder: {Current Idea Folder}
-  idea_summary: {parsed summary - UI/UX content only}
-  mockup_needs:
-    - type: dashboard
-      description: "Main analytics dashboard with charts"
-    - type: form
-      description: "User registration form"
-  design_preferences:
-    style: modern | minimal | professional
-    colors: {from idea or default}
-```
-
-**IF `mockup.figma-mcp: true`:**
-```
-1. Check Figma MCP server connection
-2. Create new Figma file or use template
-3. Generate basic layout based on idea
-4. Return Figma file link
-```
-
-**IF no tools enabled (Manual Mode):**
-```
-1. Create detailed mockup description in markdown
-2. Include ASCII art or text-based layout
-3. Document component specifications
-4. Save as mockup-description.md in {Current Idea Folder}/mockups/
-```
+**Tool-specific invocation details:** See [references/mockup-guidelines.md](references/mockup-guidelines.md) for:
+- `tool-frontend-design` skill invocation format
+- Figma MCP invocation procedure
+- Manual mode procedure
 
 **Output:** Generated mockup files/links
 
 ### Step 6: Save Artifacts
 
-**Action:** Store all mockup artifacts in the Current Idea Folder
-
-**Directory Structure:**
-```
-{Current Idea Folder}/
-├── idea-summary-vN.md
-├── mockups/
-│   ├── dashboard-v1.html      (if tool-frontend-design used)
-│   ├── dashboard-v1.css       (if tool-frontend-design used)
-│   ├── form-v1.html           (if tool-frontend-design used)
-│   ├── mockup-description.md  (if manual mode)
-│   └── figma-link.md          (if figma-mcp used)
-└── files/
-    └── (original idea files)
-```
-
-**Naming Convention:**
-```
-{mockup-type}-v{version}.{extension}
+**Action:** Store all mockup artifacts in `{Current Idea Folder}/mockups/`
 
-Examples:
-- dashboard-v1.html
-- user-form-v1.html
-- mobile-home-v1.html
-```
+**Directory structure and naming conventions:** See [references/mockup-guidelines.md](references/mockup-guidelines.md).
 
 **Output:** List of saved artifact paths (relative to Current Idea Folder)
 
 ### Step 7: Update Idea Summary
 
-**Action:** Add mockup references to the idea summary
+**Action:** Create new version `{Current Idea Folder}/idea-summary-v{N+1}.md` with mockup references
 
 **DO NOT modify existing idea-summary files.**
-Instead, create a new version: `{Current Idea Folder}/idea-summary-v{N+1}.md`
-
-**Add to Summary:**
-```markdown
-## Mockups & Prototypes
 
-| Mockup | Type | Path | Tool Used |
-|--------|------|------|-----------|
-| Dashboard | HTML | mockups/dashboard-v1.html | tool-frontend-design |
-| User Form | HTML | mockups/user-form-v1.html | tool-frontend-design |
-
-### Preview Instructions
-- Open HTML files in browser to view interactive mockups
-- Figma link: {link if figma-mcp used}
-```
+**Summary update template:** See [references/mockup-guidelines.md](references/mockup-guidelines.md).
 
 **Output:** Updated idea summary version
 
@@ -435,41 +219,19 @@ Instead, create a new version: `{Current Idea Folder}/idea-summary-v{N+1}.md`
 
 ## Skill/Task Completion Output
 
-This skill MUST return these attributes to the Task Data Model upon task completion:
-```yaml
-category: ideation-stage
-task_type: Idea Mockup
-auto_proceed: {from input Auto Proceed}
-idea_id: IDEA-XXX
-current_idea_folder: {Current Idea Folder}   # e.g., x-ipe-docs/ideas/mobile-app-idea
-mockup_tools_used:
-  - tool-frontend-design
-mockups_created:
-  - type: dashboard
-    path: {Current Idea Folder}/mockups/dashboard-v1.html
-  - type: form
-    path: {Current Idea Folder}/mockups/user-form-v1.html
-mockup_list:   # List of all mockup paths - passed to next tasks in chain
-  - {Current Idea Folder}/mockups/dashboard-v1.html
-  - {Current Idea Folder}/mockups/user-form-v1.html
-idea_summary_version: vN+1
-next_task_type: Requirement Gathering
-require_human_review: true
-task_output_links:
-  - {Current Idea Folder}/mockups/dashboard-v1.html
-  - {Current Idea Folder}/mockups/user-form-v1.html
-  - {Current Idea Folder}/idea-summary-v{N+1}.md
-```
+This skill MUST return these attributes to the Task Data Model upon task completion.
 
-**Output Links:** All paths in `task_output_links` are clickable/viewable:
-- HTML mockups can be opened in browser
-- Idea summary is markdown viewable in editor
+**Output format:** See [references/mockup-guidelines.md](references/mockup-guidelines.md) for complete output YAML structure.
 
-**Mockup List Flow:** The `mockup_list` attribute is passed through the task chain:
-```
-Idea Mockup → Requirement Gathering → Feature Breakdown → Feature Refinement → Technical Design
-```
-Each subsequent task receives and passes the mockup_list to ensure mockups are referenced throughout the development lifecycle.
+**Key output attributes:**
+- `category`: ideation-stage
+- `task_type`: Idea Mockup  
+- `current_idea_folder`: {Current Idea Folder}
+- `mockup_list`: List of all mockup paths (passed to next tasks in chain)
+- `next_task_type`: Requirement Gathering
+- `require_human_review`: true
+
+**Mockup List Flow:** The `mockup_list` is passed through: Idea Mockup → Requirement Gathering → Feature Breakdown → Feature Refinement → Technical Design
 
 ---