zy-skills

Engineering guardrails for Vibe Coding — requirement tracking, session backup, cross-model review.

Zero dependencies. No Node.js, no database, no background process. Pure Markdown files.

中文文档 | Comparison with alternatives

---

The Problem

Vibe coding is mainstream — 92% of developers use AI coding tools daily. But the #1 complaint isn't code quality. It's:

• Context evaporation — Tomorrow your AI forgets every architecture decision you made today
• Scope drift — "Add a search" becomes "rewrite the schema" across 5 sessions, and nobody stops it
• Whack-a-mole bugs — Fix one bug, create two more. AI can't see the dependency graph
• Single-model blind spots — Your AI won't catch what its own reasoning biases miss
• The 70% wall — First 70% flies, last 30% spirals into rework

The Solution — Three Skills

Skill	Solves	One-liner
zy-track	Scope drift, context loss	Anchor goals and scope exclusions across sessions
zy-session	Crash, shutdown, context wipe	30s backup, 30s restore — restores "what was I thinking"
zy-xr	Single-model blind spots	Let a different model find what yours missed

The three skills auto-link: create requirement → suggest review → record progress → suggest backup → restore links to requirement → detect pending reviews.

Quick Start

git clone https://github.com/Ian-zy1/zy-skills.git
cp -r zy-skills/skills/* ~/.claude/skills/
# restart your AI assistant, done

/zy-track new Add product search feature     # Create requirement (auto-detects project)
/zy-xr .project/requirements/001-search.md   # Cross-model review
continue                                      # Next session: goal anchoring + resume
/zy-track done 001                            # Archive with experience log

How It Works

zy-track — Goal Anchoring

Every time you resume work, zy-track re-confirms what you're building and what you're NOT building. If scope drifts, it warns you.

You: continue
AI: === Goal Anchoring ===
    🎯 Goal: keyword search + category filter + price sort
    🚫 Out of scope: search recommendations, ElasticSearch, pinyin search
    Progress: 1/5 complete

You: add search recommendations too
AI: ⚠️ Search recommendations are out of scope. Edit the requirement if needed.
You: ...never mind, let's finish what we started

Includes automatic data lineage tracking, acceptance criteria verification, and experience logging on archive.

zy-session — Structured Backup

Not a file list backup. A decision context backup.

You: /zy-recall
AI: Restored from 13 minutes ago:
    📂 Project: data-migration (directory auto-switched)
    🌿 Branch: feature/school-migration
    🔵 Thinking: score table FK dependency, might cross shards
    ✅ Decision: batch INSERT, 500K rows in 8min
    ⬜ Remaining: 4 items
    📌 Active zy-track requirement detected — resume? (auto-links)

zy-xr — Cross-Model Review

Uses a different model to review your AI's output. Finds blind spots that the original model's reasoning biases can't see.

You: /zy-xr requirements/003-export.md
AI (Claude reviewing GLM-5 output):
    ❌ "Export Excel" — 500+ teachers × 12 months, timeout?
    ❌ Permissions not considered — anyone can export all data?
    ❌ "Out of scope" section completely missing
    ✅ Found before you spend 3 days coding

Directory Structure

~/.claude/skills/
├── zy-track/
│   ├── SKILL.md
│   └── templates/
│       ├── requirement.md
│       ├── CONTEXT.md
│       └── pitfalls.md
├── zy-session/
│   ├── SKILL.md
│   └── templates/
│       ├── backup-template.md
│       └── restore-output-template.md
└── zy-xr/
    ├── SKILL.md
    ├── templates/
    │   └── review-prompt.md
    └── references/
        └── dimensions.md

Compatibility

Platform	Status
Claude Code	✅ Native ~/.claude/skills/
OpenCode + oh-my-opencode	✅ Reads the same path

Design Principles

Principle	Description
File-first	All data is Markdown. Git-trackable, human-readable, AI-native
Goal anchoring	Re-confirm goals and scope exclusions every session
Loose coupling	Each skill works independently. Linking is advisory, not mandatory
Zero ceremony	One command to trigger. No unnecessary questions
Human-driven	AI suggests, you decide

Why Not Platform Native?

CLAUDE.md and MEMORY.md solve "AI knows the tech stack" (knowledge layer). zy-skills solves "what am I building, what am I NOT building, where did I stop" (management layer). Different problems, complementary.

For detailed comparison with claude-mem (76K⭐) and ECC (183K⭐), see docs/comparison.md.

License

MIT