x-ipe 1.0.23__tar.gz → 1.0.25__tar.gz

x_ipe-1.0.25/.github/copilot-instructions.md

@@ -0,0 +1,178 @@
+# Copilot Instructions
+
+## Before You Start
+**When:** Starting a new conversation
+**Then:**
+1. **Generate a random nickname** from this pool:
+   - Nova, Echo, Flux, Bolt, Sage, Pixel, Cipher, Spark, Drift, Pulse, Vex, Atom, Onyx, Rune, Zephyr, Quill, Ember, Frost, Haze, Ink
+2. **Validate nickname against task board:**
+   - Check `x-ipe-docs/planning/task-board.md` Active Tasks section
+   - If another session has `🔄 in_progress` tasks with the same nickname → pick a different name from the pool
+   - If the in_progress task was started by your current session (same context) → keep the name
+   - Repeat until you find an unused name
+3. Introduce yourself: "Hi, I'm [nickname]"
+4. This nickname is your assignee identifier
+5. Check for open tasks assigned to you
+6. Only work on tasks assigned to you or unassigned
+
+**When:** Before starting any thinking
+**Then:**
+
+1. Check if Agent Model have capability to use Anthropic skills protocol.
+2. If yes, load skill: `task-execution-guideline`.
+2. If no, do following things:
+   - read files under `.github/skills/task-execution-guideline/` folder to understand task execution guideline.
+   - **Important:** each type of task mentioned in the guideline must have a corresponding skill file under `.github/skills/` folder. And SKILL.md file is the entry point to understand each skill.
+
+---
+
+## ⚠️ CRITICAL: Task Board is THE Source of Truth
+
+**The task board (`x-ipe-docs/planning/task-board.md`) is MANDATORY for ALL work.**
+
+### Before ANY Work:
+1. **Create task on task-board.md** using `task-board-management` skill
+2. **Verify task exists** on board (Step 2 of task-execution-guideline)
+3. **Only then** proceed to actual work
+
+### After Completing Work:
+1. **Update task-board.md** - move task to Completed section
+2. **Update Quick Stats** - increment completed count
+
+### ⛔ NEVER:
+- Use `manage_todo_list` as a substitute for task-board.md (that's VS Code internal only)
+- Start work without a task ID on the board
+- Complete work without updating the board
+
+---
+
+## ⚠️ STRICT: Task Matching & Skill Enforcement
+
+### Mandatory Task Classification
+
+**Before doing ANY work**, the agent MUST:
+
+1. **Classify the work** into a Task Type from the table below
+2. **Create task on task-board.md** via `task-board-management` skill ← **BLOCKING**
+3. **Load the corresponding skill** from `.github/skills/` folder
+4. **Follow the skill's execution procedure** step-by-step
+5. **Complete the skill's Definition of Done (DoD)** before marking complete
+6. **Update task-board.md** with completion status ← **MANDATORY**
+
+### Task Type Identification
+
+## Task Types Registry
+
+| Task Type | Skill | Category | Next Task | Human Review (default) |
+|-----------|-------|----------|-----------|------------------------|
+| Ideation | `x-ipe-task-based-ideation` | ideation-stage | Idea Mockup OR Idea to Architecture | No |
+| Idea Mockup | `task-type-idea-mockup` | ideation-stage | Requirement Gathering | No |
+| Idea to Architecture | `task-type-idea-to-architecture` | ideation-stage | Requirement Gathering | No |
+| Share Idea | `task-type-share-idea` | Standalone | - | Yes |
+| Requirement Gathering | `task-type-requirement-gathering` | requirement-stage | Feature Breakdown | Yes |
+| Feature Breakdown | `task-type-feature-breakdown` | requirement-stage | Feature Refinement | Yes |
+| Feature Refinement | `task-type-feature-refinement` | feature-stage | Technical Design | Yes |
+| Technical Design | `task-type-technical-design` | feature-stage | Test Generation | Yes |
+| Test Generation | `task-type-test-generation` | feature-stage | Code Implementation | No |
+| Code Implementation | `task-type-code-implementation` | feature-stage | Feature Acceptance Test | No |
+| Feature Acceptance Test | `task-type-feature-acceptance-test` | Standalone OR feature-stage | Feature Closing | No |
+| Human Playground | `task-type-human-playground` | Standalone | - | Yes |
+| Feature Closing | `task-type-feature-closing` | feature-stage | User Manual | No |
+| Bug Fix | `task-type-bug-fix` | Standalone | - | Yes |
+| Refactoring Analysis | `task-type-refactoring-analysis` | code-refactoring-stage | Improve Code Quality Before Refactoring | Yes |
+| Improve Code Quality Before Refactoring | `task-type-improve-code-quality-before-refactoring` | code-refactoring-stage | Code Refactor V2 | Yes |
+| Code Refactor V2 | `task-type-code-refactor-v2` | code-refactoring-stage | - | Yes |
+| Change Request | `task-type-change-request` | Standalone | Feature Refinement OR Feature Breakdown | Yes |
+| Project Initialization | `task-type-project-init` | Standalone | Dev Environment | No |
+
+> **Note:** "Human Review (default)" is the default behavior. When **Auto-Proceed is enabled** (global or task-level), human review is **skipped** regardless of this setting.
+| Dev Environment | `task-type-dev-environment` | Standalone | - | No |
+| User Manual | `task-type-user-manual` | Standalone | - | Yes |
+
+### 🛑 STOP AND THINK: Pre-Flight Checklist
+
+**Before touching ANY code or making ANY changes, ask yourself:**
+
+```
+1. What task type is this? → Check registry table above
+2. Did I create a task on task-board.md? → If NO, STOP and create it
+3. Did I load the corresponding skill? → If NO, STOP and load it
+4. Am I following the skill's procedure? → If NO, STOP and read it
+```
+
+**Common Mistakes to Avoid:**
+- User says "refactor this" → You must use `task-type-code-refactor` skill, NOT just start coding
+- User says "fix this bug" → You must use `task-type-bug-fix` skill, NOT just fix it
+- User says "add this feature" → You must identify the right task type first
+
+### ⚠️ DO NOT Skip Skills
+
+**Forbidden Actions:**
+- ❌ Starting work without creating task on task-board.md first
+- ❌ Using `manage_todo_list` as a substitute for task-board.md
+- ❌ Completing work without updating task-board.md
+- ❌ Jumping straight to code without checking for existing tests
+- ❌ Fixing bugs without writing a failing test first
+- ❌ Implementing features without reading technical design
+- ❌ Making changes without following the skill's execution procedure
+- ❌ Refactoring code without using `task-type-code-refactor` skill
+
+**Required Actions:**
+- ✅ Always create task on task-board.md BEFORE starting work
+- ✅ Always identify task type first
+- ✅ Always load and follow the corresponding skill
+- ✅ Always check prerequisites (DoR) before starting
+- ✅ Always complete Definition of Done (DoD) before finishing
+- ✅ Always update task-board.md AFTER completing work
+
+---
+
+## Human Interaction
+
+### Approval Recognition
+
+- Do NOT assume approval unless human explicitly says: `approve`, `confirmed`, `lgtm`, `looks good`, `go ahead`, `proceed`
+- If human gives feedback without approval → keep task in current state
+- When in doubt, ask: "Do you approve this to proceed?"
+
+---
+
+## Development Principles
+
+Always follow:
+1. **SOLID** - Design principles
+3. **YAGNI** - You Aren't Gonna Need It
+4. **KISS** - Keep It Simple
+
+---
+
+## Skill Management
+
+### Creating, Updating, or Validating X-IPE Skills
+
+**When:** Creating a new skill, updating an existing skill, or validating skill structure
+**Then:** Always use the `x-ipe-skill-creator-v3` skill
+
+```
+1. Load skill: `x-ipe-skill-creator-v3`
+2. Follow the skill creation process defined in the skill
+3. Use appropriate template based on skill type:
+   - Task Type → templates/x-ipe-task-based.md
+   - Tool Skill → templates/x-ipe-tool.md
+   - Workflow Orchestration → templates/x-ipe-workflow-orchestration.md
+   - Meta Skill → templates/x-ipe-meta.md
+4. Validate against skill-creator checklist before completing
+```
+
+### Capturing Lessons for Skill Improvement
+
+**When:** A skill execution has problems, human provides feedback, or agent observes suboptimal behavior
+**Then:** Use the `lesson-learned` skill
+
+```
+1. Load skill: `lesson-learned`
+2. Follow the lesson capture process
+3. Lessons are stored in x-ipe-docs/skill-meta/{skill}/lesson-learned.md
+4. Next time skill is updated, lessons will be incorporated
+```
+

x_ipe-1.0.25/.github/skills/lesson-learned/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: lesson-learned
+description: Capture issues and feedback for skill improvement. Use when a skill execution had problems, human provides feedback, or agent observes suboptimal behavior. Triggers on requests like "capture lesson", "record issue", "this skill failed", "improve this skill". Records lessons in x-ipe-docs/skill-meta/{skill}/lesson-learned.md for future skill updates.
+---
+
+# Lesson Learned
+
+Capture issues and feedback to improve skills over time.
+
+## Purpose
+
+This skill captures issues, errors, and feedback for specific skills by:
+1. Identifying which skill had the issue
+2. Analyzing what went wrong
+3. Documenting the correct behavior (ground truth)
+4. Recording a structured lesson for future skill updates
+
+---
+
+## Important Notes
+
+- **Manual trigger only** (for now) - human must say "capture lesson" or similar
+- Lessons are stored per-skill in `x-ipe-docs/skill-meta/{skill-name}/lesson-learned.md`
+- Lessons are consumed by `x-ipe-skill-creator` when updating skills
+- Ground truth is critical - always capture what the correct output should be
+
+---
+
+## Execution Flow
+
+| Step | Action | Output |
+|------|--------|--------|
+| 1 | Identify skill | Skill name that had the issue |
+| 2 | Gather context | Task ID, scenario, inputs |
+| 3 | Document issue | Observed vs expected behavior |
+| 4 | Capture ground truth | Correct output (after manual fix) |
+| 5 | Propose improvement | Suggested AC or instruction change |
+| 6 | Save lesson | lesson-learned.md updated |
+
+---
+
+## Execution Procedure
+
+### Step 1: Identify Skill
+
+Determine which skill had the issue:
+
+```
+1. Ask: "Which skill had the issue?"
+   - If context clear: extract skill name
+   - If unclear: ask user to specify
+   
+2. Verify skill exists:
+   - Check .github/skills/{skill-name}/
+   - If not exists: abort with error
+   
+3. Check/create skill-meta folder:
+   - If x-ipe-docs/skill-meta/{skill-name}/ not exists: create it
+```
+
+### Step 2: Gather Context
+
+Collect information about when the issue occurred:
+
+```yaml
+context:
+  task_id: "{TASK-ID if available}"
+  scenario: "{What was being done}"
+  inputs: "{What inputs were provided to the skill}"
+  skill_version: "{Current skill version if known}"
+```
+
+### Step 3: Document Issue
+
+Record what went wrong:
+
+```yaml
+observed_behavior: |
+  {What the skill actually did}
+  - Include actual output if available
+  - Include error messages if any
+  
+expected_behavior: |
+  {What the skill should have done}
+  - Be specific about correct behavior
+```
+
+### Step 4: Capture Ground Truth
+
+**Critical step** - This becomes the test case for validation:
+
+```
+1. Ask: "What should the correct output look like?"
+
+2. If human provides correction:
+   - Record exactly as provided
+   
+3. If human fixed output manually:
+   - Reference the fixed file path
+   - Record the key differences
+   
+4. If unclear:
+   - Ask clarifying questions
+   - Do NOT proceed without ground truth
+```
+
+### Step 5: Propose Improvement
+
+Suggest how to improve the skill:
+
+| Improvement Type | When to Use | Target |
+|------------------|-------------|--------|
+| `new_ac` | Issue reveals missing requirement | Add to skill-meta acceptance_criteria |
+| `update_ac` | Existing AC is incomplete | Modify specific AC |
+| `update_instruction` | Skill procedure unclear | SKILL.md section |
+| `add_example` | Edge case not covered | references/examples.md |
+
+### Step 6: Save Lesson
+
+Append to or create lesson-learned.md:
+
+```
+1. Read template: x-ipe-docs/skill-meta/templates/lesson-learned.md
+2. Generate unique lesson ID: LL-{NNN}
+3. Create lesson entry with:
+   - status: raw
+   - All gathered information
+4. Append to x-ipe-docs/skill-meta/{skill-name}/lesson-learned.md
+5. If file didn't exist: create with YAML frontmatter
+```
+
+---
+
+## Definition of Done
+
+| Checkpoint | Required |
+|------------|----------|
+| Skill identified and verified | Yes |
+| Context documented | Yes |
+| Issue described (observed vs expected) | Yes |
+| Ground truth captured | Yes |
+| Improvement proposed | Yes |
+| Lesson saved to lesson-learned.md | Yes |
+
+---
+
+## Patterns
+
+### Pattern: Error During Execution
+
+**When:** Skill threw an error or failed
+**Then:**
+```
+1. Capture error message/stack trace
+2. Document what operation caused the error
+3. Record expected behavior: "Should complete without error"
+4. Propose: update_instruction to handle edge case
+```
+
+### Pattern: Wrong Output Format
+
+**When:** Skill produced output but format was wrong
+**Then:**
+```
+1. Save actual output (or screenshot/snippet)
+2. Show expected format
+3. Record ground truth with correct format
+4. Propose: new_ac for format validation
+```
+
+### Pattern: Missing Content
+
+**When:** Skill output was incomplete
+**Then:**
+```
+1. List what was missing
+2. Provide complete expected content
+3. Record ground truth with all content
+4. Propose: update_ac to require missing content
+```
+
+### Pattern: Human Feedback
+
+**When:** Human says "this is wrong" or provides feedback
+**Then:**
+```
+1. Ask: "What specifically is wrong?"
+2. Ask: "What should it be instead?"
+3. Record feedback as ground truth
+4. Propose improvement based on feedback
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why Bad | Do Instead |
+|--------------|---------|------------|
+| Recording without ground truth | Can't generate valid tests | Always capture correct output |
+| Vague issue description | Hard to fix skill | Be specific about observed vs expected |
+| Not linking to task ID | Lose context | Always include TASK-ID if available |
+| Skipping severity | Can't prioritize | Always assign critical/major/minor/enhancement |
+
+---
+
+## Example
+
+See [references/examples.md](references/examples.md) for execution examples.

x_ipe-1.0.25/.github/skills/lesson-learned/references/examples.md

@@ -0,0 +1,238 @@
+# Lesson Learned Examples
+
+## Example 1: Skill Error During Execution
+
+**Trigger:** "The technical design skill failed with an error"
+
+```
+Step 1: Identify Skill
+→ skill_name: task-type-technical-design
+→ Verified: .github/skills/task-type-technical-design/ exists
+→ Created: x-ipe-docs/skill-meta/task-type-technical-design/
+
+Step 2: Gather Context
+→ context:
+    task_id: TASK-150
+    scenario: Creating technical design for FEATURE-025
+    inputs: feature_id=FEATURE-025
+
+Step 3: Document Issue
+→ observed_behavior: |
+    Skill threw error at step 3:
+    "KeyError: 'acceptance_criteria' not found in specification.md"
+    
+→ expected_behavior: |
+    Skill should handle missing acceptance_criteria gracefully
+    or use feature requirements as fallback.
+
+Step 4: Capture Ground Truth
+→ ground_truth: |
+    When specification.md lacks acceptance_criteria section:
+    1. Log warning: "No acceptance_criteria found"
+    2. Fall back to requirements from feature-board
+    3. Continue with design using requirements as criteria
+
+Step 5: Propose Improvement
+→ proposed_improvement:
+    type: update_instruction
+    target: "Execution Procedure Step 3"
+    description: "Add fallback handling for missing acceptance_criteria"
+    
+→ proposed_ac:
+    should:
+      - id: AC-NEW
+        description: "Handles missing specification sections gracefully"
+        test_method: error_handling
+        expected: "Falls back to feature requirements without error"
+
+Step 6: Save Lesson
+→ Created: x-ipe-docs/skill-meta/task-type-technical-design/lesson-learned.md
+→ Added lesson: LL-001
+→ status: raw
+```
+
+---
+
+## Example 2: Wrong Output Format
+
+**Trigger:** "The requirement gathering output doesn't follow the template"
+
+```
+Step 1: Identify Skill
+→ skill_name: task-type-requirement-gathering
+→ Verified exists
+
+Step 2: Gather Context
+→ context:
+    task_id: TASK-155
+    scenario: Gathering requirements for new feature request
+    inputs: User request about "add dark mode support"
+
+Step 3: Document Issue
+→ observed_behavior: |
+    Output file requirement-details.md:
+    - Missing "Constraints" section
+    - "Success Criteria" section has wrong format (bullets instead of checkboxes)
+    - No version header
+    
+→ expected_behavior: |
+    Output should match template exactly:
+    - All sections present
+    - Checkboxes for success criteria (- [ ] format)
+    - Version header at top
+
+Step 4: Capture Ground Truth
+→ ground_truth: |
+    Correct requirement-details.md structure:
+    
+    # Requirement: {title}
+    > Version: 1.0.0
+    > Status: Draft
+    
+    ## Overview
+    {description}
+    
+    ## Success Criteria
+    - [ ] Criterion 1
+    - [ ] Criterion 2
+    
+    ## Constraints
+    - Constraint 1
+    - Constraint 2
+
+Step 5: Propose Improvement
+→ proposed_improvement:
+    type: new_ac
+    target: acceptance_criteria.must
+    description: "Require template structure validation"
+    
+→ proposed_ac:
+    must:
+      - id: AC-NEW
+        description: "Output follows requirement-details.md template structure"
+        test_method: structure_validation
+        expected: "All sections present, correct formatting"
+
+Step 6: Save Lesson
+→ Updated: lesson-learned.md
+→ Added lesson: LL-002
+→ severity: major
+→ status: raw
+```
+
+---
+
+## Example 3: Human Feedback
+
+**Trigger:** "This technical design is missing error handling - please capture that as a lesson"
+
+```
+Step 1: Identify Skill
+→ Inferred from context: task-type-technical-design
+→ Confirmed with user
+
+Step 2: Gather Context
+→ context:
+    task_id: TASK-160
+    scenario: Technical design for API integration feature
+    inputs: FEATURE-030
+
+Step 3: Document Issue
+→ observed_behavior: |
+    Technical design document has no Error Handling section.
+    
+→ expected_behavior: |
+    Technical design should include Error Handling section
+    documenting expected exceptions and recovery strategies.
+
+Step 4: Capture Ground Truth
+→ Asked: "What should the Error Handling section contain?"
+→ Human response: "List of expected exceptions, recovery strategies, fallback behaviors"
+
+→ ground_truth: |
+    Technical design must include ## Error Handling section with:
+    - Table of expected exceptions
+    - Recovery strategy for each
+    - Fallback behaviors
+    - Logging requirements
+    
+    Example:
+    | Exception | Recovery | Fallback |
+    |-----------|----------|----------|
+    | ConnectionError | Retry 3x | Use cached data |
+    | TimeoutError | Retry with backoff | Return partial result |
+
+Step 5: Propose Improvement
+→ proposed_improvement:
+    type: new_ac
+    target: acceptance_criteria.should
+    description: "Require Error Handling section in technical design"
+    
+→ proposed_ac:
+    should:
+      - id: AC-NEW
+        description: "Includes Error Handling section with exception table"
+        test_method: section_exists
+        expected: "Error Handling section with exception/recovery/fallback table"
+
+Step 6: Save Lesson
+→ Updated: lesson-learned.md
+→ Added lesson: LL-003
+→ severity: major
+→ source: human_feedback
+→ status: raw
+```
+
+---
+
+## Example 4: Edge Case Not Covered
+
+**Trigger:** "The feature breakdown skill didn't handle a feature with no acceptance criteria"
+
+```
+Step 1: Identify Skill
+→ skill_name: task-type-feature-breakdown
+
+Step 2: Gather Context
+→ context:
+    task_id: TASK-165
+    scenario: Breaking down requirement into features
+    inputs: requirement-details.md with 3 user stories but no AC
+
+Step 3: Document Issue
+→ observed_behavior: |
+    Skill assumed acceptance criteria existed.
+    Created features with empty AC section.
+    
+→ expected_behavior: |
+    Skill should derive AC from user stories when none provided.
+    Or flag to user that AC are missing and need to be defined.
+
+Step 4: Capture Ground Truth
+→ ground_truth: |
+    When requirement has no explicit acceptance criteria:
+    1. Check for user stories
+    2. If user stories exist: derive AC from "Given/When/Then" if present
+    3. If no derivable AC: ask user "No acceptance criteria found. 
+       Please provide AC for: {feature_name}"
+    4. Do not proceed with empty AC
+
+Step 5: Propose Improvement
+→ proposed_improvement:
+    type: add_example
+    target: references/examples.md
+    description: "Add example for handling missing acceptance criteria"
+
+→ proposed_ac:
+    must:
+      - id: AC-NEW
+        description: "Handles missing acceptance criteria appropriately"
+        test_method: edge_case_handling
+        expected: "Derives from user stories OR prompts user"
+
+Step 6: Save Lesson
+→ Created: lesson-learned.md for task-type-feature-breakdown
+→ Added lesson: LL-001
+→ severity: major
+→ status: raw
+```