cleveragents/cleveragents-core

Fork 3

feat(skill): add registry flattening and capability summaries #165

New issue

Closed

opened 2026-02-22 23:39:45 +00:00 by freemo · 3 comments

freemo commented

2026-02-22 23:39:45 +00:00

Owner

Metadata

Commit Message: feat(skill): add registry flattening and capability summaries
Branch: feature/m4-skill-registry-core

Background

Skill flattening resolves includes, named tool refs, and anonymous inline tools into a deterministic flattened list. Include cycles are detected with clear error paths. Per-tool override merging uses shallow merge with an explicit disallow list for non-overridable fields.

Acceptance Criteria

Implement skill flattening that resolves includes, named tool refs, and anonymous inline tools into a deterministic flattened list.
Detect include cycles and emit a clear error listing the cycle path (skillA -> skillB -> skillA).
Implement per-tool override merging (shallow merge) with explicit disallow list for non-overridable fields.
Compute capability summary (read/write/checkpointable/idempotent) for each skill from flattened tool metadata.
Add SkillRegistry.tools(name) and SkillRegistry.validate_plan(plan) to support actor activation and plan validation.

Definition of Done

This issue is complete when:

All subtasks below are completed and checked off.
A Git commit is created where the first line of the commit message matches
the Commit Message in Metadata exactly, followed by a blank line, then
additional lines providing relevant details about the implementation. The
commit body should be appropriate in size for a commit message and relatively
complete in describing what was done.
The commit is pushed to the remote on the branch matching the Branch in
Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and
merged before this issue is marked done.

Subtasks

Implement skill flattening that resolves includes, named tool refs, and anonymous inline tools into a deterministic flattened list.
Detect include cycles and emit a clear error listing the cycle path (skillA -> skillB -> skillA).
Implement per-tool override merging (shallow merge) with explicit disallow list for non-overridable fields.
Compute capability summary (read/write/checkpointable/idempotent) for each skill from flattened tool metadata.
Add SkillRegistry.tools(name) and SkillRegistry.validate_plan(plan) to support actor activation and plan validation.
Add deterministic ordering for flattened tools (include order, then tool name).
Add error reporting that includes source file and line when overrides fail.
Add docs/reference/skill_registry.md describing flattening rules, overrides, and validation errors.
Add example of flattened output with inline tools and includes.
Tests (Behave): Add features/skill_flatten.feature scenarios for includes, overrides, cycle detection, and missing tool refs.
Tests (Robot): Add robot/skill_flatten.robot for add/list/show/tools flows.
Tests (ASV): Add benchmarks/skill_flatten_bench.py for flattening throughput.
Verify coverage >=97% via nox -s coverage_report.
Run nox (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Section: #### M2: Actor Graphs + Tool Sources (Day 14)
Status: In Review

## Metadata - **Commit Message**: `feat(skill): add registry flattening and capability summaries` - **Branch**: `feature/m4-skill-registry-core` ## Background Skill flattening resolves `includes`, named tool refs, and anonymous inline tools into a deterministic flattened list. Include cycles are detected with clear error paths. Per-tool override merging uses shallow merge with an explicit disallow list for non-overridable fields. ## Acceptance Criteria - [x] Implement skill flattening that resolves `includes`, named tool refs, and anonymous inline tools into a deterministic flattened list. - [x] Detect include cycles and emit a clear error listing the cycle path (`skillA -> skillB -> skillA`). - [x] Implement per-tool override merging (shallow merge) with explicit disallow list for non-overridable fields. - [x] Compute capability summary (read/write/checkpointable/idempotent) for each skill from flattened tool metadata. - [x] Add `SkillRegistry.tools(name)` and `SkillRegistry.validate_plan(plan)` to support actor activation and plan validation. ## Definition of Done This issue is complete when: - All subtasks below are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. The commit body should be appropriate in size for a commit message and relatively complete in describing what was done. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. ## Subtasks - [x] Implement skill flattening that resolves `includes`, named tool refs, and anonymous inline tools into a deterministic flattened list. - [x] Detect include cycles and emit a clear error listing the cycle path (`skillA -> skillB -> skillA`). - [x] Implement per-tool override merging (shallow merge) with explicit disallow list for non-overridable fields. - [x] Compute capability summary (read/write/checkpointable/idempotent) for each skill from flattened tool metadata. - [x] Add `SkillRegistry.tools(name)` and `SkillRegistry.validate_plan(plan)` to support actor activation and plan validation. - [x] Add deterministic ordering for flattened tools (include order, then tool name). - [x] Add error reporting that includes source file and line when overrides fail. - [x] Add `docs/reference/skill_registry.md` describing flattening rules, overrides, and validation errors. - [x] Add example of flattened output with inline tools and includes. - [x] Tests (Behave): Add `features/skill_flatten.feature` scenarios for includes, overrides, cycle detection, and missing tool refs. - [x] Tests (Robot): Add `robot/skill_flatten.robot` for add/list/show/tools flows. - [x] Tests (ASV): Add `benchmarks/skill_flatten_bench.py` for flattening throughput. - [x] Verify coverage >=97% via `nox -s coverage_report`. - [x] Run `nox` (all default sessions, including benchmark), fix any errors if needed ensuring nox passes across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. **Section**: #### M2: Actor Graphs + Tool Sources (Day 14) **Status**: In Review

freemo added this to the v3.1.0 milestone

2026-02-22 23:39:45 +00:00

freemo added the

labels

2026-02-22 23:39:45 +00:00

freemo self-assigned this

2026-02-22 23:39:45 +00:00

freemo added a new dependency

2026-02-22 23:54:03 +00:00

#356 Epic: Actor Graphs + Tool Sources (M2)

freemo commented

2026-02-23 18:30:52 +00:00

Author

Owner

Expected completion (Day 15 rebaseline): Day 26 / 2026-03-06

**Expected completion (Day 15 rebaseline):** Day 26 / 2026-03-06

freemo added the due date 2026-02-26

2026-02-23 18:41:25 +00:00

freemo removed a dependency

2026-02-23 20:33:16 +00:00

#356 Epic: Actor Graphs + Tool Sources (M2)

freemo added a new dependency

2026-02-23 20:35:23 +00:00

#393 Epic: Skill & Tool Lifecycle

freemo referenced this issue

2026-02-24 03:42:29 +00:00

Epic: Skill & Tool Lifecycle #393

freemo referenced this issue from a commit

2026-02-24 13:13:44 +00:00

feat(skill): add registry flattening and capability summaries

~~freemo referenced this issue 2026-02-24 13:13:54 +00:00~~

feat(skill): add registry flattening and capability summaries #415

freemo added

and removed

labels

2026-02-24 13:14:02 +00:00

freemo commented

2026-02-24 13:14:26 +00:00

Author

Owner

Implementation Complete — PR #415

Summary

Registry flattening and capability summaries implemented via enhancements to SkillResolver (domain layer) and new methods on SkillRegistry (skills package).

Files Changed (8 files, +1557 lines)

Modified source files:

src/cleveragents/domain/models/core/skill.py — Added _NON_OVERRIDABLE_FIELDS frozenset, _validate_override_keys() helper, per-include override propagation in _resolve_recursive() with before/after key snapshots
src/cleveragents/skills/registry.py — Added tools() method returning tuple[list[ResolvedToolEntry], SkillCapabilitySummary], and validate_plan() method for plan skill reference validation

New test files:

features/skill_flatten.feature — 13 Behave scenarios (ordering, includes, inline tools, cycles, overrides, non-overridable fields, capability summaries, tools(), validate_plan(), de-duplication, shallow merge)
features/steps/skill_flatten_steps.py — Step definitions with unique flatten-prefixed patterns
robot/skill_flatten.robot — 11 Robot Framework integration tests
robot/helper_skill_flatten.py — Robot helper keywords
benchmarks/skill_flatten_bench.py — 4 ASV benchmark suites (FlattenSimple, FlattenDeep, FlattenWide, ComputeSummary)

Documentation:

docs/reference/skill_registry.md — Added flattening rules, override merging, non-overridable fields, capability summary fields, validate_plan() usage, error reference

Quality Gates

Gate	Status
Lint	PASS
Typecheck	PASS — 0 errors
Unit tests	PASS — 131 scenarios across 5 related features
Integration tests	PASS — 673/673
Security scan	PASS
Dead code	PASS
Docs	PASS
Build	PASS
Benchmark	PASS

Branch & Commit

Branch: feature/m4-skill-registry-core
Commit: 54dd6c2 — feat(skill): add registry flattening and capability summaries
PR: #415

## Implementation Complete — PR #415 ### Summary Registry flattening and capability summaries implemented via enhancements to `SkillResolver` (domain layer) and new methods on `SkillRegistry` (skills package). ### Files Changed (8 files, +1557 lines) **Modified source files:** - `src/cleveragents/domain/models/core/skill.py` — Added `_NON_OVERRIDABLE_FIELDS` frozenset, `_validate_override_keys()` helper, per-include override propagation in `_resolve_recursive()` with before/after key snapshots - `src/cleveragents/skills/registry.py` — Added `tools()` method returning `tuple[list[ResolvedToolEntry], SkillCapabilitySummary]`, and `validate_plan()` method for plan skill reference validation **New test files:** - `features/skill_flatten.feature` — 13 Behave scenarios (ordering, includes, inline tools, cycles, overrides, non-overridable fields, capability summaries, tools(), validate_plan(), de-duplication, shallow merge) - `features/steps/skill_flatten_steps.py` — Step definitions with unique `flatten`-prefixed patterns - `robot/skill_flatten.robot` — 11 Robot Framework integration tests - `robot/helper_skill_flatten.py` — Robot helper keywords - `benchmarks/skill_flatten_bench.py` — 4 ASV benchmark suites (FlattenSimple, FlattenDeep, FlattenWide, ComputeSummary) **Documentation:** - `docs/reference/skill_registry.md` — Added flattening rules, override merging, non-overridable fields, capability summary fields, validate_plan() usage, error reference ### Quality Gates | Gate | Status | |------|--------| | Lint | PASS | | Typecheck | PASS — 0 errors | | Unit tests | PASS — 131 scenarios across 5 related features | | Integration tests | PASS — 673/673 | | Security scan | PASS | | Dead code | PASS | | Docs | PASS | | Build | PASS | | Benchmark | PASS | ### Branch & Commit - Branch: `feature/m4-skill-registry-core` - Commit: `54dd6c2` — `feat(skill): add registry flattening and capability summaries` - PR: #415

freemo referenced this issue from a pull request that will close it,

2026-02-24 14:30:31 +00:00

feat(skill): add registry flattening and capability summaries #415

freemo added a new dependency

2026-02-24 14:30:38 +00:00

#415 feat(skill): add registry flattening and capability summaries

freemo referenced this issue from a commit

2026-02-24 20:32:49 +00:00

feat(skill): add registry flattening and capability summaries

freemo commented

2026-02-24 20:48:00 +00:00

Author