feat: typed params, DDE nodes, wrapping skill refs, and best practices - #9
Merged
sergio-sisternes-epam merged 5 commits intoMay 24, 2026
Merged
Conversation
Evolve the AML context-contract to support named, typed parameters alongside the existing text-only interface body pattern. Interface definitions can now contain: - <param> declarations with name, type, required, default, values, and description - <returns> declarations with name, type, values, and description - <reads> and <writes> file I/O declarations with comma-separated glob patterns Supported parameter types: string, enum, number, boolean, path, list. Key design decisions: - Fully backward compatible: text-only interface bodies remain valid - Context-sensitive parsing: <returns>, <reads>, <writes> are only recognised inside interface definition bodies, not globally - Invocation <param> semantics are unchanged (name + value) - Self-closing declarations supported for all new tags - Validation: unique names, valid types, enum requires values, default validated against declared type This enables self-documenting skill interfaces like brain-query with proper function-signature semantics instead of cramming everything into four fixed channels. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extend AML's interface/implementation definitions with three new capabilities that bridge AML with Diagram-Driven Execution (DDE): Interface definitions now support: - <skill ref="..." role="..."/> — reference other skills (e.g. DDE enforcement) - <tool allow="..."/> / <tool deny="..."/> — declare tool constraints as part of the interface contract (self-closing, mutually exclusive) Implementation definitions now support: - <node name="..." type="tool|prompt"> — structured DDE node declarations with optional <tool use="..."/> child elements Changes span AST, parser, validator, registry, Python bindings, grammar, documentation, and 10 new tests (4 parser + 7 validator inline tests, 4 conformance files). All 142 tests pass with zero clippy warnings. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add support for the wrapping form of <skill ref> inside implementation
bodies. The wrapping form allows scoped governance — a skill ref that
encloses <node> declarations, with nodes extracted into the parent
implementation's nodes list for validation and registry registration.
Parser changes:
- Add try_parse_skill_ref_with_content() for implementation bodies
- Add ParsedImplementationBody struct (fixes clippy type_complexity)
- Add skill_refs field to ImplementationDefinition AST variant
- Update validator to validate skill refs in implementations
Documentation:
- New best-practices.mdx guide with 5 real-world AML patterns:
1. Wrapping <skill ref> for scoped governance
2. Placeholder convention: {curly braces} not <angle brackets>
3. Description prefix convention: define/ and implement/
4. Interface/Implementation split pattern
5. <tool allow> with usage annotations
- Updated grammar.ebnf with wrapping SkillRefDecl production
- Cross-reference from interfaces guide to best practices
Tests: 144 pass (2 new parser tests + conformance file), zero clippy.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a new skill at .github/skills/aml-authoring/ that guides agents writing well-formed, idiomatic AML content. Covers: - 5 hard conventions (placeholder syntax, description prefixes, interface/implementation split, wrapping skill refs, tool annotations) - Interface definition template with typed params, returns, reads/writes - Implementation definition template with DDE nodes and wrapping refs - Worked example: brain-query skill pair - Common mistakes table Includes references/grammar.md with the full AML grammar and validation rules for progressive disclosure. Designed via the Genesis 8-step process with handoff packet persisted to session plan.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Owner
Author
Phase 4 added: Genesis-designed
|
Fix formatting issues flagged by CI. No logic changes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Evolves AML's context-contract with three commits:
1. Typed parameter declarations (
f23277a)<param>,<returns>,<reads>,<writes>inside interface definitions2. DDE bridge elements (
977d6c0)<skill ref="..." role="..."/>— skill references in interfaces<tool allow="..."/>/<tool deny="..."/>— tool constraints in interfaces<node name="..." type="tool|prompt">with<tool use="..."/>— DDE node declarations in implementations3. Wrapping skill ref + best practices (
78b4ab3)<skill ref>...</skill>form for scoped governance in implementation bodiesTest coverage
144 tests (up from 113 baseline), zero clippy warnings.
Files changed
AST, parser, validator, registry, Python bindings, EBNF grammar, two documentation guides, and 5 conformance test files.
cc @sergio-sisternes-epam for review