@meyverick/agentic 5.0.2

package/skills/openspec-learn/references/improvement-patterns.md

@@ -0,0 +1,155 @@
+# Improvement Patterns
+
+Common improvement types and templates.
+
+## Pattern 1: Fix Validation Failures
+
+**Trigger**: Report shows test cases failed
+
+**Template**:
+```
+1. Identify failed test case
+2. Analyze failure reason
+3. Update SKILL.md to address failure
+4. Re-run validation
+5. If passes → update changelog (PATCH)
+6. If still fails → try alternative approach
+```
+
+**Example**:
+- Failed: "Description doesn't trigger on casual prompts"
+- Fix: Broaden description scope
+- Changelog: `### Fixed - Description trigger accuracy`
+
+## Pattern 2: Address Follow-ups
+
+**Trigger**: Report has follow-up items
+
+**Template**:
+```
+1. List all follow-up items
+2. Prioritize by impact/effort
+3. Implement highest priority
+4. Update changelog (MINOR for new features)
+```
+
+**Example**:
+- Follow-up: "Add gotcha for edge case X"
+- Fix: Add to gotchas section
+- Changelog: `### Added - Gotcha for edge case X`
+
+## Pattern 3: Upgrade Based on Patterns
+
+**Trigger**: Report shows new best practices
+
+**Template**:
+```
+1. Identify new pattern
+2. Check if skill already follows it
+3. If not, update skill to follow pattern
+4. Update references if needed
+5. Update changelog (MINOR)
+```
+
+**Example**:
+- Pattern: "All skills should include fragility matching"
+- Fix: Add fragility section to SKILL.md
+- Changelog: `### Added - Fragility matching section`
+
+## Pattern 4: Meta-Improvement
+
+**Trigger**: Pattern is generalizable to all skills
+
+**Template**:
+```
+1. Identify generalizable pattern
+2. Check if create-skill already covers it
+3. If not, update create-skill:
+   - SKILL.md workflow
+   - scripts/
+   - references/
+   - assets/templates/
+4. Validate create-skill
+5. Update create-skill changelog (MINOR)
+6. Optionally propagate to existing skills
+```
+
+**Example**:
+- Pattern: "All skills should validate near-miss negatives"
+- Fix: Add to create-skill evaluation phase
+- Changelog: `### Added - Near-miss negative evaluation`
+
+## Pattern 5: Description Optimization
+
+**Trigger**: Report shows description doesn't trigger well
+
+**Template**:
+```
+1. Analyze trigger test results
+2. Identify failing queries
+3. Revise description:
+   - Broaden scope for should-trigger failures
+   - Add specificity for shouldn't-trigger failures
+4. Re-test triggers
+5. Update changelog (PATCH)
+```
+
+**Example**:
+- Failing: "Create a skill for X" doesn't trigger
+- Fix: Add "create" to description keywords
+- Changelog: `### Fixed - Description trigger keywords`
+
+## Pattern 6: Antipattern Fix
+
+**Trigger**: Audit detects antipatterns
+
+**Template**:
+```
+1. Identify antipattern violation
+2. Analyze why it occurred
+3. Fix the violation:
+   - A1: Remove phantom tool references
+   - A2: Consolidate duplicated invariants
+   - A3: Convert to imperative triggers
+   - A4: Single source for cheat-sheets
+   - A5: Reduce prose bloat
+   - A14: Decompose omnibus file
+   - A15: Add concrete success metrics
+4. Re-run audit
+5. Update changelog (PATCH)
+```
+
+## Pattern 7: Fragility Reclassification
+
+**Trigger**: Report shows wrong fragility classification
+
+**Template**:
+```
+1. Identify misclassified task
+2. Determine correct fragility:
+   - Mutation → strict
+   - Read-only → loose
+   - Creative → low specificity
+3. Update instructions accordingly
+4. Update changelog (MINOR if significant)
+```
+
+## Changelog Entry Templates
+
+### For Fixes
+```markdown
+### Fixed
+- <what was fixed> (from report: <report-name>)
+```
+
+### For Additions
+```markdown
+### Added
+- <what was added> (from report: <report-name>)
+```
+
+### For Changes
+```markdown
+### Changed
+- <what was changed> (from report: <report-name>)
+```

package/skills/openspec-learn/references/report-analysis.md

@@ -0,0 +1,104 @@
+# Report Analysis Guide
+
+How to parse and analyze reports generated by `opsx-report`.
+
+## Report Structure
+
+Reports follow OKF v0.2 format:
+
+```yaml
+---
+type: OpenSpec Report
+title: "Report: <change-name>"
+description: "<summary>"
+status: stable
+tags: [openspec, <schema>, <capability>]
+generated:
+  by: opsx-report/1.0
+  at: <timestamp>
+sources:
+  - id: proposal
+    resource: artifacts/proposal.md
+  - id: design
+    resource: artifacts/design.md
+  - id: specs
+    resource: artifacts/specs/
+  - id: tasks
+    resource: artifacts/tasks.md
+stale_after: <date>
+---
+```
+
+## Extraction Points
+
+### From Frontmatter
+
+| Field | Extract | Use |
+|-------|---------|-----|
+| `tags` | Skill name, capability-path | Identify related skill |
+| `generated.at` | Timestamp | Track when report was created |
+| `sources` | Artifact paths | Locate original artifacts |
+| `stale_after` | Date | Check if report is stale |
+
+### From Sections
+
+| Section | Extract | Use |
+|---------|---------|-----|
+| Problem Statement | Why skill exists | Understand purpose |
+| Approach | Decisions with rationale | Understand design choices |
+| What Changed | Requirements added/modified/removed | Understand scope |
+| Implementation | Tasks completed, files created | Understand what was built |
+| Validation | Test results, pass/fail | Identify failures to fix |
+| Trade-offs | Risks and mitigations | Understand constraints |
+| Follow-ups | Deferred work | Identify improvements to make |
+
+## Analysis Patterns
+
+### Pattern 1: Validation Failures
+
+```
+IF validation section shows failures:
+  → Identify which tests failed
+  → Analyze why they failed
+  → Fix skill to address failures
+  → Re-run validation
+```
+
+### Pattern 2: Follow-ups
+
+```
+IF follow-ups section has items:
+  → List all follow-up items
+  → Prioritize by impact
+  → Implement highest priority
+  → Update changelog
+```
+
+### Pattern 3: Trade-offs
+
+```
+IF trade-offs section has items:
+  → Evaluate if trade-offs are still valid
+  → Check if alternatives are now viable
+  → Consider upgrading if better option exists
+```
+
+### Pattern 4: Generalizable Patterns
+
+```
+IF report shows pattern applicable to all skills:
+  → Check if create-skill already covers it
+  → If not, update create-skill
+  → Propagate to existing skills
+```
+
+## Quality Signals
+
+From report analysis, extract quality signals:
+
+- **Validation pass rate**: Percentage of tests that passed
+- **Antipattern count**: Number of antipatterns detected
+- **Description trigger rate**: How well description triggers
+- **Task completion rate**: Percentage of tasks completed
+
+Use these to measure improvement after changes.

package/skills/openspec-learn/references/skill-quality.md

@@ -0,0 +1,103 @@
+# Skill Quality Criteria
+
+Quality metrics and thresholds for skill evaluation.
+
+## Quality Dimensions
+
+### 1. Structural Quality
+
+- **SKILL.md exists**: Required
+- **Frontmatter valid**: name, description present
+- **Name format**: lowercase, hyphens, 1-64 chars
+- **Description format**: 1-1024 chars, imperative
+- **Directory structure**: scripts/, references/, assets/ present
+- **File references resolve**: All markdown links valid
+
+### 2. Content Quality
+
+- **Description specificity**: Imperative, intent-driven, not vague
+- **Instruction clarity**: Actionable, not ambiguous
+- **Progressive disclosure**: SKILL.md < 500 lines
+- **Gotchas present**: Environment-specific facts documented
+- **Examples provided**: BAD/GOOD pairs where helpful
+
+### 3. Fragility Matching
+
+- **Mutation tasks**: Strict preconditions, gating
+- **Read-only tasks**: Loose triggers, latitude
+- **Creative tasks**: Low specificity, examples
+
+### 4. Antipattern Compliance
+
+No violations of:
+- A1: Phantom tool references
+- A2: Duplicated invariants
+- A3: Passive-voice triggers
+- A4: Copy-pasted cheat-sheets
+- A5: Prose bloat in triggers
+- A14: Single file omnibus
+- A15: Vague success bars
+
+### 5. Trigger Accuracy
+
+- **Description triggers on relevant prompts**: >80% pass rate
+- **Description doesn't trigger on irrelevant prompts**: >90% pass rate
+- **Near-miss negatives pass**: 100% for mutation tools
+
+## Quality Score
+
+Calculate quality score (0-100):
+
+```
+Structural: 30 points
+- Valid frontmatter: 10
+- Valid name: 5
+- Valid description: 5
+- Directory structure: 5
+- File references: 5
+
+Content: 30 points
+- Description specificity: 10
+- Instruction clarity: 10
+- Progressive disclosure: 5
+- Gotchas present: 5
+
+Fragility: 15 points
+- Correct classification: 10
+- Appropriate specificity: 5
+
+Antipatterns: 15 points
+- No violations: 15
+- Minor violations: 10
+- Major violations: 0
+
+Trigger: 10 points
+- Positive trigger rate: 5
+- Negative trigger rate: 5
+```
+
+## Thresholds
+
+| Score | Quality Level | Action |
+|-------|---------------|--------|
+| 90-100 | Excellent | No improvements needed |
+| 70-89 | Good | Minor improvements |
+| 50-69 | Fair | Significant improvements |
+| 0-49 | Poor | Major improvements or rebuild |
+
+## Measurement
+
+Before improvement:
+1. Run validate-structure.sh → structural score
+2. Run audit-antipatterns.sh → antipattern score
+3. Review content → content score
+4. Calculate total quality score
+
+After improvement:
+1. Re-run all checks
+2. Calculate new quality score
+3. Calculate delta (improvement percentage)
+
+If delta < 0 (quality degraded) → rollback
+If delta = 0 → plateau reached
+If delta > 0 → improvement successful

package/skills/openspec-learn/references/tool-type-detection.md

@@ -0,0 +1,30 @@
+# Tool Type Detection
+
+## Detection Matrix
+
+| Report Content | Tool Type | Action |
+|----------------|-----------|--------|
+| New skill files in artifacts/ | New skill | Create proposal for new skill |
+| Existing skill improvement | Skill update | Create proposal for skill update |
+| New prompt files in artifacts/ | New prompt | Create proposal for new prompt |
+| Both skill and prompt | Combo | Create proposal for both |
+| Knowledge gaps in assessment | Reference/docs | Create proposal for reference materials |
+| Generic workflow improvement | Prompt | Create proposal for new prompt |
+
+## Detection Signals
+
+### From Report Metadata
+- `tags` field → skill/prompt name
+- `capability-path` → skill identifier
+- `type` field → report category
+
+### From Artifacts
+- `skills/` directory → skill
+- `prompts/` directory → prompt
+- Both → combo
+- `references/` → reference materials
+
+### From Assessment
+- Knowledge gaps → reference materials needed
+- Tool improvements → skill/prompt updates
+- Documentation gaps → new documentation

package/skills/openspec-report/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: openspec-report
+description: >
+  Generate self-reflection (meditation) on an archived OpenSpec change.
+  Use when the user wants to create a report from an archived change,
+  document lessons learned, or capture AI agent self-assessment.
+  Do NOT use when exploring ideas (use openspec-explore), implementing changes,
+  creating proposals, or analyzing reports for skill improvements.
+allowed-tools: Bash(openspec:*), Bash(ls:*), Bash(mkdir:*), Bash(mv:*)
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: agentic
+  version: "1.0.1"
+positive_triggers:
+  - "generate a report from an archived change"
+  - "document what was learned from this change"
+  - "create self-reflection on completed work"
+anti_triggers:
+  - "explore ideas and investigate problems"
+  - "implement a proposal or apply changes"
+  - "analyze reports to improve skills"
+---
+
+# Openspec Report
+
+Generate self-reflection (meditation) on archived OpenSpec changes.
+
+**Timestamp rule**: fill the `{{timestamp}}` frontmatter placeholder by running `date -u +"%Y-%m-%dT%H:%M:%SZ"` at generation time. Never hand-write or estimate timestamps.
+
+## Workflow
+
+### Phase 1: Find Archive
+
+Archives have date prefixes. Search intelligently:
+
+**Exact match first:**
+```bash
+ls openspec/changes/archive/<name>/ 2>/dev/null
+```
+
+**Fuzzy search if not found:**
+```bash
+ls openspec/changes/archive/ | grep -i "<name>"
+```
+
+Handle results:
+- One match → use it
+- Multiple matches → ask user to select
+- No matches → error with available archives
+
+### Phase 2: Read Archive
+
+Read `.openspec.yaml` for metadata, then all planning artifacts: proposal.md, design.md, specs/, tasks.md.
+
+### Phase 3: Create Report Directory
+
+Create `openspec/reports/<name>/` (just report.md and assessment.md — no subdirectories).
+
+### Phase 4: Generate report.md
+
+Use template at `assets/templates/report.md.template`. Fill placeholders with self-reflection content.
+
+**Meditation sections:**
+- What Happened
+- What I Learned
+- Mental Model Shift (1–2 lines: `Before (old model):` / `After (new model):` — e.g., `Before: C# null check (if x != null)` → `After: Rust Option (if let Some(x))`)
+- Surprise vs Expectation (Expected vs Surprise — 1–2 lines)
+- Concrete Gotcha (single before/after code snippet with Signal — e.g., `if (user != null)` vs `if let Some(u) = user`)
+- Time Cost (where time went — e.g., `60m borrow checker, 10m logic`)
+- Re-use Score (`high/medium/low — one-line why` — e.g., `high — every Rust task touches Option`)
+- What I'd Do Differently
+- Key Decisions (table)
+- Trade-offs Made (table)
+- Follow-ups
+- Archive Reference
+
+### Phase 5: Generate assessment.md
+
+Use template at `assets/templates/assessment.md.template`. Fill with experiential reflection.
+
+**Assessment sections:**
+- How It Felt (What Went Well / What Went Poorly)
+- Difficulty Ratings (5 dimensions)
+- What I Was Lacking (knowledge gaps, skills gaps, Before → After Model — complements report's Mental Model Shift)
+- What Would Help Next Time (process, tools, documentation, Re-use Score)
+- Time Cost (mirrors report)
+- Surprise vs Expectation (mirrors report)
+
+### Phase 6: Validate
+
+Check report has all meditation sections and assessment has minimum quality bar.
+
+### Phase 7: Display Summary
+
+Report location, archive reference, files generated.
+
+## Gotchas
+
+- **Archive is source of truth**: Reference it, don't copy content into reports.
+- **Reports are meditation**: Self-reflection on experience, not documentation of what happened.
+- **Minimum quality bar**: At least 2 items per reflection section, at least 1 knowledge gap identified, and one Concrete Gotcha snippet when a mistake or discovery occurred.
+- **1–2 line shifts only; single gotcha snippet**: Mental Model Shift Before/After are 1–2 lines each; Concrete Gotcha is one before/after pair with Signal — prevents report bloat while preserving C#→Rust transferability.
+- **Latest version only**: If no name specified, use most recent archive.

package/skills/openspec-report/assets/templates/assessment.md.template

@@ -0,0 +1,84 @@
+---
+type: Assessment
+title: "Assessment: {{change-name}}"
+description: "AI agent meditation on the experience"
+generated:
+  by: openspec-report/1.0
+  at: {{timestamp}}
+---
+
+# Assessment: {{change-name}}
+
+*Meditation on the experience of this change.*
+
+## How It Felt
+
+### What Went Well
+
+{{what_went_well}}
+
+### What Went Poorly
+
+{{what_went_poorly}}
+
+## Difficulty Ratings
+
+| Dimension | Rating (1-5) | Notes |
+|-----------|--------------|-------|
+| Overall | {{overall_rating}} | {{overall_notes}} |
+| Technical complexity | {{technical_rating}} | {{technical_notes}} |
+| Scope clarity | {{scope_rating}} | {{scope_notes}} |
+| Integration | {{integration_rating}} | {{integration_notes}} |
+| Time estimation | {{time_rating}} | {{time_notes}} |
+
+## What I Was Lacking
+
+### Knowledge gaps
+
+{{knowledge_gaps}}
+
+### Skills gaps
+
+{{skills_gaps}}
+
+### Before → After Model
+
+<!-- 1-2 lines complementing report's Mental Model Shift: what model did you hold before vs after. ex: Before: C# null is runtime value → After: Rust Option is type-level -->
+
+Before: {{before_model}}
+
+After: {{after_model}}
+
+## What Would Help Next Time
+
+### Process improvements
+
+{{process_improvements}}
+
+### Tool improvements
+
+{{tool_improvements}}
+
+### Documentation gaps
+
+{{documentation_gaps}}
+
+### Re-use Score
+
+<!-- high/medium/low + one-line why — feeds learn's frequency×cost prioritization. ex: high — every Rust task touches Option -->
+
+{{reuse_score}} — {{reuse_reason}}
+
+## Time Cost
+
+<!-- Where time went — mirrors report's Time Cost for learn clustering. ex: 60m borrow checker, 10m logic -->
+
+{{time_cost}}
+
+## Surprise vs Expectation
+
+<!-- 1-2 lines mirroring report; helps learn prioritize surprises -->
+
+Expected: {{expected}}
+
+Surprise: {{surprise}}

package/skills/openspec-report/assets/templates/report.md.template

@@ -0,0 +1,92 @@
+---
+type: OpenSpec Report
+title: "Report: {{change-name}}"
+description: "Self-reflection on archived change"
+generated:
+  by: openspec-report/1.0
+  at: {{timestamp}}
+---
+
+# Report: {{change-name}}
+
+*Self-reflection on archived change: {{archive-path}}*
+
+## What Happened
+
+{{what_happened}}
+
+## What I Learned
+
+{{what_i_learned}}
+
+## Mental Model Shift
+
+<!-- 1-2 lines: Before (old model) → After (new model). ex: Before: C# null check (if x != null) → After: Rust Option (if let Some(x) = x) — absence is type-level, not runtime value -->
+
+Before (old model): {{mental_model_before}}
+
+After (new model): {{mental_model_after}}
+
+## Surprise vs Expectation
+
+<!-- 1-2 lines: what you expected vs what actually happened -->
+
+Expected: {{expected}}
+
+Surprise: {{surprise}}
+
+## Concrete Gotcha
+
+<!-- Single before/after code snippet with signal. ex: before (wrong): if (user != null) → after (right): if let Some(u) = user — signal: compiler forces None handling -->
+
+Before (wrong):
+
+```{{gotcha_lang_before}}
+{{gotcha_before}}
+```
+
+After (right):
+
+```{{gotcha_lang_after}}
+{{gotcha_after}}
+```
+
+Signal: {{gotcha_signal}}
+
+## Time Cost
+
+<!-- Where time went. ex: 60m borrow checker, 10m logic -->
+
+{{time_cost}}
+
+## Re-use Score
+
+<!-- high/medium/low + one-line why. ex: high — every Rust task touches Option -->
+
+{{reuse_score}} — {{reuse_reason}}
+
+## What I'd Do Differently
+
+{{what_i_would_do_differently}}
+
+## Key Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+{{key_decisions_table}}
+
+## Trade-offs Made
+
+| Risk | Mitigation |
+|------|------------|
+{{tradeoffs_table}}
+
+## Follow-ups
+
+{{followups}}
+
+## Archive Reference
+
+- **Location**: {{archive_path}}
+- **Date**: {{archive_date}}
+- **Schema**: {{schema_name}}