Skip to content

About

No description, website, or topics provided.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

12 Commits

Folders and files

Repository files navigation

Semantic Alignment

Your agent says “done.” You still don’t know what it skipped, changed, or decided for you.

Semantic Alignment compares what you asked for with what was built, then shows the differences in a visual report—with violations of your limits first.

A file copier's actual flow reveals an overwrite that violates the user's limit, plus recursive scanning and logs the agent added.

Illustrative example. Added choices can be useful—the point is to let you see and judge them.

See the decisions behind the code

  • Spot violated limits. See the exact user restriction, the behavior that violates it, and the evidence.
  • See what was missed or added. Surface omitted requirements and added defaults, dependencies, checks, storage or interaction choices.
  • Skim first, inspect when needed. Start with a difference summary, then open a finding to explore its flow, original wording and sources. Unverified behavior stays visible.

Use it to review a feature built by an agent, check a handoff, or pick up a project whose decisions have become hard to track.

See the real output

We used Semantic Alignment to check itself. You're welcome to explore this project's own user agreements and the resulting report—open a finding, follow it into a diagram, and inspect the original wording and evidence.

Open the live report · Read the user agreements · Read the Markdown findings

Actual difference summary from this project's semantic check.

Actual expandable diagram and finding details from this project's semantic check.

Screenshots of the published report, in the user's original Chinese. This dated check retains its scope, unresolved verification gaps and full evidence; the showcase notes explain what changed afterward.

Try it on your next change

Install SKILL.md, agents/, references/, scripts/ and assets/ together as the semantic-alignment skill using your agent’s supported installation mechanism. Point it at your project or change, then ask:

Use semantic-alignment to check whether this matches my requirements. Show what you added or decided without me specifying it, and put violations of my constraints first.

Start from the conversation or existing requirements; you don’t need to prepare a semantic record yourself. The Skill first records your goals, constraints and agreements in the project’s designated Markdown document, or SEMANTICS.md by default, keeps relevant meaning active during implementation, and uses those records as the baseline when you request a check.

To reload the project's purpose and constraints in one command:

python3 <installed-skill>/scripts/read_context.py

The reader keeps the original wording and enclosing project/stage context so the Agent can check design direction as well as implementation limits. It searches upward within Git/home boundaries, preferring the nearest .semantics-path declaration, then the nearest SEMANTICS.md. For an external record, put its file path in a local .semantics-path (relative to that declaration's directory), or pass the Markdown file directly. Missing content and unsupported structures are explicitly reported.

You get a separate summary, an expandable HTML/SVG report and editable Markdown findings. Reports are local; generation uses Python 3. The agent makes the semantic judgments, and the templates handle presentation. Conclusions remain tied to the evidence actually checked.

The public showcase is specific to this project; using the Skill does not publish your records. Showcase records and reports are excluded from the default GitHub ZIP download, so you can browse them online without installing them. A full Git clone includes them for anyone who wants an offline copy.

Skill instructions · Checking method · Report templates

About

No description, website, or topics provided.

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages