→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises

[!TIP] New workflow now available! We've rebuilt SynergySpec-SelfEvolving with a new artifact-guided workflow.

Run /synspec:onboard to get started, or use the standard path: /synspec:propose -> /synspec:apply -> /synspec:verify -> /synspec:learn -> /synspec:archive. See the SynergySpec-SelfEvolving workflow guide.

Teams

Using SynergySpec-SelfEvolving in a team? Join the SynergySpec-SelfEvolving Discord for support and rollout questions.

See it in action

You: /synspec:propose add-dark-mode
AI:  Created synergyspec-selfevolving/changes/add-dark-mode/
     Generating planning artifacts...
     ✓ proposal.md — why we're doing this, what's changing
     ✓ usecases.md — actor goals, scenarios, and traceability IDs
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

You: /synspec:apply
AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

You: /synspec:verify
AI:  Implementation matches the change artifacts.
     Ready for review and learning.

You: /synspec:learn
AI:  Reviewed the completed change and captured reusable lessons:
     - Keep theme state initialization separate from render-time DOM reads
     - Future UI toggles should include persistence scenarios in usecases.md

You: /synspec:archive
AI:  Archived to synergyspec-selfevolving/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

Quick Start

Requires Node.js 20.19.0 or higher.

Install SynergySpec-SelfEvolving globally — pick one:

Option 1 — From npm registry (recommended)

npm install -g synergyspec-selfevolving@latest

Option 2 — From a local clone with pnpm

git clone https://github.com/ZhifeiDou/SynergySpec-SelfEvolving.git
cd SynergySpec-SelfEvolving
pnpm install && pnpm run build
npm install -g .

Then navigate to your project directory and initialize:

cd your-project
synergyspec-selfevolving init

Now tell your AI: /synspec:propose <what-you-want-to-build>

[!NOTE] Not sure if your tool is supported? View the full list – we support 20+ tools and growing.

Also works with pnpm, yarn, bun, and nix. See installation options.

Docs

→ Getting Started: first steps → Workflows: combos and patterns → Commands: slash commands & skills → CLI: terminal reference → Self-Evolution Loop: the loop-v2 in-context RL surface → Supported Tools: tool integrations & install paths → Concepts: how it all fits → Multi-Language: multi-language support → Customization: make it yours

Why SynergySpec-SelfEvolving?

AI coding assistants are powerful but unpredictable when requirements live only in chat history. SynergySpec-SelfEvolving adds a lightweight spec layer so you agree on what to build before any code is written.

• Agree before you build — human and AI align on specs before code gets written
• Stay organized — each change gets its own folder with proposal, use cases, specs, design, and tasks
• Work fluidly — update any artifact anytime, no rigid phase gates
• Review and learn - verify completed work, capture reusable lessons, then archive with a durable trail
• Use your tools — works with 20+ AI assistants via slash commands

How we compare

vs. Spec Kit (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of Markdown, Python setup. SynergySpec-SelfEvolving is lighter and lets you iterate freely.

vs. Kiro (AWS) — Powerful but you're locked into their IDE and limited to Claude models. SynergySpec-SelfEvolving works with the tools you already use.

vs. nothing — AI coding without specs means vague prompts and unpredictable results. SynergySpec-SelfEvolving brings predictability without the ceremony.

Updating SynergySpec-SelfEvolving

Upgrade the package

npm install -g synergyspec-selfevolving@latest

Refresh agent instructions

Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:

synergyspec-selfevolving update

Building from Source

See Option 2 in Quick Start for the clone → build → global-install flow. Verify with:

synergyspec-selfevolving --version

Usage Notes

Model selection: SynergySpec-SelfEvolving works best with high-reasoning models. We recommend Opus 4.5 and GPT 5.2 for both planning and implementation.

Context hygiene: SynergySpec-SelfEvolving benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.

Self-evolution

Normal SynergySpec-SelfEvolving usage is a human-reviewed development workflow: propose -> apply -> verify -> learn -> archive. The learn step reviews a completed, verified change and captures reusable lessons for future work. It is not a promise that the AI will automatically rewrite itself.

The self-evolution machinery lives in-tree under src/core/fitness and src/core/self-evolution, exposed through the synergyspec-selfevolving self-evolution subcommands (not as an ordinary day-to-day skill). It treats the spec workflow as a learnable system — a change is a forward pass through the artifact templates; learn runs the backward pass (a per-change loss); and an in-context-RL episode improves one design 策略 POLICY lineage from a graded advantage, with a rollback that fires before any new edit.

What actually works today:

• Per-change fitness loss (learn): loss = 0.7·(1 − pass_rate) + 0.3·health_penalty, in [0,1]. The functional term comes from the change's gen-test/run-test pass rate; the code-health term is fed by a swappable MetricSource selected via health: in synergyspec-selfevolving/config.yaml. New projects scaffold source: local (default-on): a dependency-free, multi-language analyzer (scripts/code-health.py, Python 3 stdlib only) that scores Python, Rust, C, and C++ by computing the SlopCodeBench structural_erosion and verbosity scores (for Python, the slop rules are the actual SlopCodeBench v0.3 ast-grep rule set, bundled) — no server, no network. Set source: stub to make the loss functional-only; sonarqube is also supported; local-python is a back-compat alias for local. See docs/customization.md.
• Rollout/critic separation (learn → synergyspec-selfevolving-self-evolving): the end-of-cycle critique runs in a fresh-context critic subagent — an always-installed utility skill that reads only the on-disk record (transcripts, hints, evolution result, learn report) and returns a ## Critic Verdict block that the thin learn relays. The session that did the work never grades its own rollout; hosts without subagents run the critic inline, marked as degraded isolation. Headless and fresh-context invokers can pass explicit trajectory handles (--transcript / --session-id on learn, learn handoff, learn debug-trajectory, and evolve-from-edits, or the SYNERGYSPEC_SELFEVOLVING_TRANSCRIPT / SYNERGYSPEC_SELFEVOLVING_SESSION_ID env vars; flags beat env vars, transcript beats session-id). An explicit handle beats change-window discovery and never silently grades another session: an unresolvable flag is an up-front error (exit non-zero), while a missing env handle fails closed — no trajectory, and the observed-verified gate refuses to promote.
• Code-health gate (the episode's evolving agent / evolve-from-edits): a measured code-health regression vs the last accepted state blocks promotion (and surfaces a loud health-signal-unavailable observation if a configured analyzer can't run). No health signal ⇒ no gate, so the loop is never blocked on a missing measurement.
• Candidate proposals (self-evolution propose-canonical): turns aggregated learn hints into human-gated candidate packages under .synergyspec-selfevolving/self-evolution/candidates/. Proposal-only — no canonical file is modified, and the frozen gen-test/run-test oracle is never touched.
• In-context-RL episode (self-evolution episode --change <name>): runs ONE completed change through a fixed, code-spawned pipeline. A two-arm forward grades the 主智能体 MAIN AGENT (the frozen current 策略 POLICY) from the change's learn report against a CRITIC AGENT（基线智能体 baseline agent） that reruns the prior policy on the same change; a 奖励智能体 REWARD AGENT computes advantage ＝ reward(主臂) − reward(基线臂) and names the gap; on a bad advantage the orchestrator rolls the 策略 POLICY back before the 演进智能体 EVOLVING AGENT is called; the evolving agent then makes ONE bounded edit (or refuses) after the static / observed-GREEN / 范围⊆诊断 gates pass, writing the next policy version onto your LOCAL files — no candidate dir, no republish. A frozen target (per the per-target evolution policy) is skipped. Inspect the lineage with self-evolution policy show [--target <id>], re-enter a partial run with self-evolution episode resume <id>, and manually restore a version with self-evolution policy rollback --target <id> --yes. See docs/evaluation-lab.md.
• Per-target evolution scope (selfEvolution: in synergyspec-selfevolving/config.yaml): one switch decides which canonical targets may evolve, honored end-to-end by learn → propose-canonical → the static gate → promotion. New projects scaffold a design-only policy (default: frozen with artifact-template:design evolvable), so the loop focuses on the design template out of the box. Widen it with default: evolvable or per-target evolve: true, or scope a single run with --evolve-target / --freeze-target. The frozen oracle/gate files are never reachable by any policy.

What is not built yet (don't infer it from the architecture diagrams):

• No autonomous multi-episode breeding loop. Each self-evolution episode improves the policy from one change's graded advantage; it never fans out competing variants or runs unattended generations. New manual candidates only come from the human-gated propose-canonical step.
• No measured benchmark gains. The mechanisms are implemented and unit-tested, but the loop has not been run end-to-end to produce quantitative results.
• The earlier out-of-tree evolve/ DGM lab (and its pnpm evolve harness) and the genetic-algorithm outer loop (self-evolution evolve / --replay) have been removed; the technique was internalized into src/core and re-homed on the loop-v2 in-context-RL episode.

Contributing

Small fixes — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.

Larger changes — For new features, significant refactors, or architectural changes, please submit an SynergySpec-SelfEvolving change proposal first so we can align on intent and goals before implementation begins.

When writing proposals, keep the SynergySpec-SelfEvolving philosophy in mind: we serve a wide variety of users across different coding agents, models, and use cases. Changes should work well for everyone.

AI-generated code is welcome — as long as it's been tested and verified. PRs containing AI-generated code should mention the coding agent and model used (e.g., "Generated with Claude Code using claude-opus-4-5-20251101").

Development

• Install dependencies: pnpm install
• Build: pnpm run build
• Test: pnpm test
• Develop CLI locally: pnpm run dev or pnpm run dev:cli
• Conventional commits (one-line): type(scope): subject

Other

SynergySpec-SelfEvolving collects anonymous usage stats.

We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.

Opt-out: export SYNERGYSPEC_SELFEVOLVING_TELEMETRY=0 or export DO_NOT_TRACK=1

See MAINTAINERS.md for the list of core maintainers and advisors who help guide the project.

License

MIT