Integrate the SkillOpt in the specmem

Author: Shashikant86

CHANGELOG.md

@@ -8,22 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- Initial release of SpecMem
-- Core memory bank with chunking, ranking, and lifecycle management
-- SpecIR canonical representation for specifications
-- Adapters for Kiro, Cursor, Claude Code, SpecKit, and Tessl
-- LanceDB as default vector database backend
-- Support for ChromaDB and Qdrant backends
-- Local embeddings via SentenceTransformers
-- Cloud embedding providers (OpenAI, Anthropic, Google, Together)
-- SpecImpact graph for code-to-spec dependency analysis
-- SpecDiff for temporal spec intelligence and drift detection
-- Test mapping engine with framework-agnostic support
-- Streaming context API with token budget optimization
-- SpecValidator for specification quality assurance
-- CLI with init, scan, build, query, and impact commands
-- Python client API for agent integration
-- Web UI for browsing and managing specifications
+- N/A
 
 ### Changed
 - N/A
@@ -40,12 +25,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Security
 - N/A
 
+## [0.2.0] - 2026-05-26
+
+### Added
+- Optimized skill artifacts for `.codex/skills/*/SKILL.md` and `.claude/skills/*/SKILL.md`.
+- `specmem guidelines optimize` for promoting a candidate skill or generating one from an instruction.
+- `specmem guidelines score-skill` for static skill quality checks.
+- `specmem guidelines optimized-status` for raw, optimized, stale, rejected, and invalid artifact states.
+- `specmem build --optimize-skills` to index accepted optimized skill artifacts.
+- Optimized skill provenance tags in indexed memory blocks.
+- Public `specmem.guidelines` optimized-skill APIs.
+- User, CLI, API, and memory-pattern documentation for optimized skills.
+
+### Changed
+- Agent guidance indexing can now opt into accepted optimized skill content while keeping default builds unchanged.
+
+### Deprecated
+- N/A
+
+### Removed
+- N/A
+
+### Fixed
+- Fixed package version mismatch between `pyproject.toml`, lockfile metadata, and `specmem.__version__`.
+- Prevented generated candidates from being copied over themselves during promotion.
+
+### Security
+- N/A
+
 ## [0.1.0] - 2025-12-01
 
 ### Added
 - Initial public release
 - Developed as part of the Kiroween Hackathon, December 2025
 - IP of Superagentic AI
 
-[Unreleased]: https://github.com/Shashikant86/specmem/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/Shashikant86/specmem/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/Shashikant86/specmem/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/Shashikant86/specmem/releases/tag/v0.1.0

docs/advanced/agent-memory-patterns.md

@@ -51,6 +51,11 @@ Instruction files are pinned by default. Skills are indexed as procedural
 memory, but they are not pinned because agents should load them only when the
 task matches the skill.
 
+Skills can also be optimized before indexing. SpecMem stores accepted optimized
+artifacts under `.specmem/skillopt/` and uses them only when
+`specmem build --optimize-skills` is requested. See
+[Optimized Skills](../user-guide/optimized-skills.md).
+
 ## Demo Flow
 
 Build the memory index:

docs/api/guidelines.md

@@ -139,6 +139,37 @@ interface ConversionResult {
 }
 ```
 
+### Optimized Skill APIs
+
+The optimized-skill helpers are available from `specmem.guidelines`:
+
+```python
+from pathlib import Path
+
+from specmem.guidelines import OptimizedSkillStore, score_skill_static
+
+workspace = Path(".")
+store = OptimizedSkillStore(workspace)
+
+score, issues = score_skill_static(
+    Path(".codex/skills/review/SKILL.md").read_text()
+)
+
+result = store.promote_candidate(
+    Path(".codex/skills/review/SKILL.md"),
+    Path("/tmp/review-best-skill.md"),
+    score_before=0.62,
+    score_after=0.74,
+    evaluator="codex-rollout",
+)
+
+status = store.status(Path(".codex/skills/review/SKILL.md"))
+optimized = store.resolve(Path(".codex/skills/review/SKILL.md"))
+```
+
+`resolve()` returns `None` when the artifact is missing, rejected, stale, or
+invalid. `status()` gives the user-facing state and reason.
+
 ## Examples
 
 ### List all guidelines

docs/changelog.md

@@ -8,27 +8,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- **Spec Coverage Analysis** - Analyze gaps between acceptance criteria and tests
-  - `specmem cov` - Show overall coverage summary
-  - `specmem cov report` - Detailed coverage report per feature
-  - `specmem cov suggest` - Get test suggestions for uncovered criteria
-  - `specmem cov badge` - Generate coverage badge for README
-  - `specmem cov export` - Export coverage data (JSON/Markdown)
-- Coverage API methods in `SpecMemClient`:
-  - `get_coverage()` - Analyze spec coverage
-  - `get_coverage_suggestions()` - Get test suggestions
-  - `get_coverage_badge()` - Generate badge markdown
-- Documentation site with MkDocs Material theme
-- Comprehensive API reference
-- Advanced configuration guide
-- User guide for Spec Coverage
+- N/A
 
 ### Changed
-- Improved error messages in CLI
-- Updated CLI index with coverage command
+- N/A
 
 ### Fixed
-- Memory leak in large spec collections
+- N/A
+
+---
+
+## [0.2.0] - 2026-05-26
+
+### Added
+
+- **Optimized Skills** - Validate and index improved agent skill artifacts
+  - `specmem guidelines optimize` - Generate or promote optimized skill candidates
+  - `specmem guidelines score-skill` - Run static quality checks for skills
+  - `specmem guidelines optimized-status` - Show raw, optimized, stale, rejected, and invalid artifact states
+  - `specmem build --optimize-skills` - Use accepted optimized skill artifacts during memory indexing
+- Optimized skill artifact storage under `.specmem/skillopt/`
+- Provenance tags for optimized skill memory blocks
+- Public Python APIs for optimized skill artifact management
+- User, CLI, API, and advanced memory-pattern documentation for optimized skills
+
+### Changed
+
+- Agent guidance indexing can opt into accepted optimized skill content while default builds keep indexing source skills.
+
+### Fixed
+
+- Aligned package version metadata across `pyproject.toml`, `uv.lock`, and `specmem.__version__`.
+- Avoided same-file candidate copy failures during generated skill promotion.
+
+---
+
+## [0.1.1] - 2026-05-26
+
+### Added
+
+- Spec Coverage Analysis commands and docs.
+- Documentation site, API reference, and advanced configuration guide.
+
+### Changed
+
+- Improved CLI error messages.
+
+### Fixed
+
+- Memory handling improvements for large spec collections.
 
 ---
 
@@ -100,6 +128,8 @@ First public release of SpecMem - Cognitive Memory Layer for AI Coding Agents.
 
 | Version | Date | Highlights |
 |---------|------|------------|
+| 0.2.0 | 2026-05-26 | Optimized Skills |
+| 0.1.1 | 2026-05-26 | Spec Coverage and documentation |
 | 0.1.0 | 2025-12-01 | Initial release |
 
 ## Upgrade Guide

docs/cli/build.md

@@ -27,6 +27,7 @@ The command uses `.specmem.toml` from the target repository when present.
 | Option | Description | Default |
 |--------|-------------|---------|
 | `--output`, `-o` | Output directory | `<PATH>/.specmem` |
+| `--optimize-skills` | Use validated optimized skill artifacts from `.specmem/skillopt` when available | `false` |
 
 ## Inputs
 
@@ -39,6 +40,13 @@ The command uses `.specmem.toml` from the target repository when present.
 Instruction files are pinned in memory by default. Skill files are indexed as
 procedural memory and selected by task intent.
 
+Optimized skill artifacts are opt-in. Run `specmem guidelines optimize` to
+validate and promote a candidate skill, then build with `--optimize-skills` to
+index the accepted `best_skill.md` instead of the raw source skill. Artifacts are
+ignored if the source skill changed after validation.
+
+See [Optimized Skills](../user-guide/optimized-skills.md) for the full workflow.
+
 ## Generated Files
 
 | File | Purpose |
@@ -68,6 +76,12 @@ specmem build ../service-api
 specmem build . --output ./build/specmem
 ```
 
+### Build With Validated Optimized Skills
+
+```bash
+specmem build --optimize-skills
+```
+
 ### Build with Qdrant
 
 Configure Qdrant in `.specmem.toml`:

docs/cli/guidelines.md

@@ -16,6 +16,9 @@ specmem guidelines [OPTIONS] [COMMAND]
 | `show` | Show full content of a specific guideline |
 | `convert` | Convert a guideline to another format |
 | `convert-all` | Convert all guidelines to a target format |
+| `score-skill` | Score a skill document with static optimization checks |
+| `optimize` | Validate and promote an optimized skill artifact |
+| `optimized-status` | Show optimized-skill artifact status |
 
 ## Options
 
@@ -122,6 +125,59 @@ specmem guidelines convert-all claude --no-preview
 specmem guidelines convert-all steering --source claude --no-preview
 ```
 
+### Optimize Skill Artifacts
+
+Use `optimize` to generate or promote a candidate `SKILL.md` into
+`.specmem/skillopt/`. Accepted artifacts are consumed only when
+`specmem build --optimize-skills` is used.
+
+```bash
+specmem guidelines score-skill .codex/skills/review/SKILL.md
+
+specmem guidelines optimize .codex/skills/review/SKILL.md \
+  --instruction "tighten this for code review tasks and make retrieval keywords explicit"
+
+specmem guidelines optimize .codex/skills/review/SKILL.md \
+  --candidate /tmp/review-best-skill.md \
+  --score-before 0.62 \
+  --score-after 0.74 \
+  --evaluator codex-rollout
+```
+
+`--instruction` mode uses the optional OpenAI dependency and requires
+`OPENAI_API_KEY`. It accepts changed candidates that pass static checks without
+regressing. `--candidate` mode accepts only when the candidate improves the
+provided scores, or the static score when no scores are supplied.
+
+For a complete guide, see [Optimized Skills](../user-guide/optimized-skills.md).
+
+Check optimized artifact status:
+
+```bash
+specmem guidelines optimized-status
+specmem guidelines optimized-status --robot
+```
+
+Accepted optimized skills can also be written back to the source skill when you
+want the optimized document to become canonical:
+
+```bash
+specmem guidelines optimize .codex/skills/review/SKILL.md \
+  --candidate /tmp/review-best-skill.md \
+  --score-before 0.62 \
+  --score-after 0.74 \
+  --write-source
+```
+
+The command writes:
+
+| File | Purpose |
+|------|---------|
+| `.specmem/skillopt/<skill>/initial_skill.md` | Source skill snapshot |
+| `.specmem/skillopt/<skill>/candidate_skill.md` | Candidate snapshot |
+| `.specmem/skillopt/<skill>/best_skill.md` | Accepted optimized skill |
+| `.specmem/skillopt/<skill>/evaluation_report.json` | Gate result and provenance |
+
 ## Output Formats
 
 ### Table (default)

docs/user-guide/guidelines.md

@@ -12,6 +12,8 @@ SpecMem detects and parses guidelines from:
 | **Cursor** | `.cursorrules` | Cursor AI rules file |
 | **Kiro** | `.kiro/steering/*.md` | Kiro steering files |
 | **Agents** | `AGENTS.md` | Generic agent instructions |
+| **Codex skills** | `.codex/skills/*/SKILL.md` | Task-routed procedural skills |
+| **Claude skills** | `.claude/skills/*/SKILL.md` | Task-routed procedural skills |
 
 ## Viewing Guidelines
 
@@ -65,6 +67,31 @@ View full content of a guideline:
 specmem guidelines show <guideline-id>
 ```
 
+Score and promote an optimized skill candidate:
+
+```bash
+specmem guidelines score-skill .codex/skills/review/SKILL.md
+
+specmem guidelines optimize .codex/skills/review/SKILL.md \
+  --instruction "tighten this for code review tasks and make retrieval keywords explicit"
+
+specmem guidelines optimize .codex/skills/review/SKILL.md \
+  --candidate /tmp/review-best-skill.md \
+  --score-before 0.62 \
+  --score-after 0.74 \
+  --evaluator codex-rollout
+```
+
+Accepted optimized skills are stored under `.specmem/skillopt/` and are used
+only when building with:
+
+```bash
+specmem build --optimize-skills
+```
+
+See [Optimized Skills](optimized-skills.md) for the full workflow, artifact
+layout, and gate behavior.
+
 ## Converting Guidelines
 
 Convert guidelines between formats to share with team members using different tools.