https://github.com/sanzhardanybayev/synergy
Author validated MDX spec sessions with live browser preview. Turns vague requests into agent-ready plans for Claude Code.
https://github.com/sanzhardanybayev/synergy
agentic-ai agentic-workflow ai claude claude-code development llm planning prd preview specification
Last synced: 5 days ago
JSON representation
Author validated MDX spec sessions with live browser preview. Turns vague requests into agent-ready plans for Claude Code.
- Host: GitHub
- URL: https://github.com/sanzhardanybayev/synergy
- Owner: sanzhardanybayev
- License: mit
- Created: 2026-05-21T11:36:28.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-23T20:01:29.000Z (11 days ago)
- Last Synced: 2026-06-23T21:21:21.629Z (11 days ago)
- Topics: agentic-ai, agentic-workflow, ai, claude, claude-code, development, llm, planning, prd, preview, specification
- Language: TypeScript
- Homepage:
- Size: 1.16 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Synergy
[](LICENSE)
[](https://www.claude.com/claude-code)
[](package.json)
[](tsconfig.json)
**Spec-driven planning for Claude Code.** Turn vague requests into MDX specifications with status badges, phase plans, agent allocations, charts, and cross-references — rendered live in your browser as you author them, then implemented phase-by-phase with live status and a resumable hand-off trail.
Markdown specs go stale in a terminal. Synergy gives agents a tight component vocabulary, a validator that enforces it, and a Vite preview that hot-reloads on every save.
## Demo
The preview at `http://localhost:4321` gives each MDX file its own route (`/s//overview`, `/architecture`, `/implementation`, `/phases/`), a hierarchical left sidebar (sessions dropdown, spec rows, phases nested under Implementation), and per-page copy-path buttons for the session dir, the current page, and the orchestrator. The orchestrator opens as a right-side slide-out drawer (ESC or backdrop to close) rendering `orchestrator.md`, and every page hot-reloads as Claude Code edits the MDX.
## Edit & review in the browser
The preview isn't read-only — you can fix and annotate specs without a round-trip through Claude:
- **Inline edits.** Prose blocks (paragraphs, list items, headings) are editable in place. Changes live in a browser-side buffer with an explicit **Apply** (writes the MDX file) or **Discard** per block — plus **Apply all / Discard all** in the top toolbar. Never auto-saves; an unload guard warns on unsaved edits.
- **Comments.** Select any text, click the **+**, and leave a note for Claude. Each comment is a markdown file under `.synergy/feedback//` with a line/col + surrounding-context anchor so it survives later edits.
- **Diff view.** Toggle **🔍 Diff** on any page to highlight what changed since you last reviewed the file (git-backed: committed + uncommitted), then **Mark as reviewed** to advance the cursor.
- **Hand back to Claude.** Run `/synergy-feedback` — the `synergy:address-feedback` skill reads the open-comment queue for the browser-active session, edits each referenced location, and marks every comment resolved or rejected (never silently dropped).
Edits, comments, and review state all persist to disk (MDX files, `.synergy/feedback/`, and a gitignored `review-state.json`) — git is the version history, so there's no database.
## Execute & hand off
Authoring is half the loop. Once a plan exists, agents implement against it — and Synergy records what actually happened in a committed `.state/` sidecar per session, so progress is visible and a fresh-context agent can pick up cleanly:
- **Disciplined execution.** `/synergy-execute ` works one phase at a time and **can't move past a phase boundary** without recording it: it flips the phase status, writes a terse boundary note, drops ad-hoc findings, and updates the resume pointer — all through the CLI, never by hand-editing state. It fans out sub-agents and teams per the `` plan (model + effort + count), and takes run-time directives ("only Phase 1", "use sonnet this run") that layer over the plan without mutating it.
- **Clean hand-off.** `/synergy-continue ` is the fresh-context entry point: it reads the resume pointer and journals *first* (state → strategy → detail), then continues from exactly where the last agent stopped. Clear the session, start a new one, and nothing is lost.
- **Live progress in the browser.** Every `` badge reflects real status from `.state/`, and a 📊 **Progress drawer** shows the derived rollup (e.g. "2 / 5 phases done"), per-phase journals, and the cross-cutting log — hot-reloading like everything else.
Per-phase status and journals are the source of truth; overall progress is **derived** (never stored, so it can't drift). The `.state/` directory is committed to git — it's the shared hand-off record, not per-user scratch.
## Install
Prerequisites: **Node ≥ 20**, **pnpm** (`corepack enable` if missing).
```
/plugin marketplace add sanzhardanybayev/synergy
/plugin install synergy@synergy
/synergy-setup
```
`/synergy-setup` runs `pnpm install && pnpm build` inside the plugin once. After that, the slash commands and skills are ready.
Install from a local clone
```bash
git clone https://github.com/sanzhardanybayev/synergy
# In Claude Code:
/plugin marketplace add /absolute/path/to/synergy
/plugin install synergy@synergy
/synergy-setup
```
## Quick start
```
/synergy-init # once per project
/synergy-spec "Add rate limiting" # creates a session + opens browser
# ...edit MDX with Claude Code, preview hot-reloads...
/synergy-validate # before commit
/synergy-execute # implement it, phase-by-phase (state-tracked)
```
That's the loop. The first command scaffolds `.synergy/sessions/` in your project. The second invokes the `synergy:create-spec` skill — which reasons about scope, picks `.synergy/sessions/YYYY-MM-DD-add-rate-limiting/`, scaffolds the overview + optional architecture/implementation/phase folders, and opens your browser. The third checks schemas and cross-references before you ship. The fourth implements the plan one phase at a time, recording status and findings as it goes — and `/synergy-continue` picks it back up in a fresh session.
## Reference
### Slash commands
| Command | Purpose |
|---|---|
| `/synergy-init` | Scaffold `.synergy/` in the current project. Once per project. |
| `/synergy-spec ""` | Create a new spec session (also auto-starts preview, opens browser). |
| `/synergy-validate [session]` | Validate schemas + cross-refs. Zero errors before commit. |
| `/synergy-feedback [session]` | Address browser-collected comments for the active session (edits specs, resolves/rejects each). |
| `/synergy-execute [session] [directives]` | Implement a session phase-by-phase, updating execution state at each boundary. |
| `/synergy-continue [session] [directives]` | Continue an in-progress session from its execution-state hand-off. |
| `/synergy-preview-start` | Boot the preview server on port 4321. Idempotent. |
| `/synergy-preview-stop` | Kill the preview server, remove PID file. |
| `/synergy-preview-status` | Report running / stopped, pid, URL. |
| `/synergy-setup` | One-time bootstrap (install + build). |
### CLI subcommands
For terminal users — available at `node "$CLAUDE_PLUGIN_ROOT/packages/cli/dist/cli.js" ...` after `/synergy-setup`. Spec authoring is a skill, not a CLI command — use `/synergy-spec` (which invokes the `synergy:create-spec` skill).
| Command | Flags | Purpose |
|---|---|---|
| `synergy init` | `--root ` | Scaffold `.synergy/` |
| `synergy preview ` | `--root`, `--port` (default 4321) | `start \| stop \| status` |
| `synergy validate [session]` | `--root` | Validate sessions in `.synergy/sessions/` |
| `synergy phase set ` | `--root`, `--note` | Record a phase status + optional boundary note |
| `synergy log ` | `--root`, `--phase `, `--global` | Append a finding to a phase or the global journal |
| `synergy continue ` | `--root`, `--next `, `--note` | Write the hand-off pointer a fresh agent reads first |
| `synergy status ` | `--root` | Print the execution-state rollup (phases done / total) |
### Daemon HTTP API (performance path)
When the preview server is running on port 4321, skills and agents use these HTTP endpoints
instead of spawning a fresh `node cli.js` process (~55 ms each). They hit the warm, cached
server (~5 ms) and write the same git-committed `.state/` files as the CLI. The CLI remains
the offline fallback when the preview is not running.
| Method + path | Replaces | Body / query |
|---|---|---|
| `POST /api/phase` | `synergy phase set` | `{session, phaseId, status, note?}` |
| `POST /api/log` | `synergy log` | `{session, text, phase?, global?}` |
| `POST /api/resume` | `synergy continue` | `{session, next?, note?}` |
| `GET /api/validate?session=` | `synergy validate` | — (returns ValidationReport JSON) |
| `GET /api/progress?session=` | `synergy status` | — |
| `POST /api/scaffold` | per-file mkdir/write | `{session, dirs?, files:[{path,content}]}` |
| `POST /api/feedback/resolve-batch` | per-comment PATCH loop | `{items:[{id,status,resolution?,rejection_reason?}]}` |
### Spec-kit components
Imported from `@synergy/spec-kit`. Props are schema-validated; cross-references are link-checked.
| Component | Required props | One-line purpose |
|---|---|---|
| `` | `value` | Lifecycle badge: `draft`, `proposed`, `in-progress`, `blocked`, `done`, `shipped` |
| `` | `number`, `title` | Phase summary card for the index in `02-implementation.mdx`; give it a stable `id` slug so execution state and live status badges bind to it. The real phase body lives in `phases/-/spec.mdx` |
| `` | `milestones` | Ordered visual milestones with optional dates and statuses |
| `` | `slug`, `title` | Link card to a sibling spec file |
| `` | `to` | Inline reference; `to=""`, `"#"`, or `"phases/"` for phase folders |
| `` | `entries` | Table of agents (`sub-agent`, `agent-team`, `human`), ownership, and per-agent fan-out (`model`, `effort`, `count`) that `/synergy-execute` spawns against |
| `` | `name`, `members` | Group of contributors with roles |
| `` | `name`, `role`, `scope` | Reviewer and their sign-off scope |
| `` | `question` | Unresolved decision blocking progress |
| `` | `title`, `severity` | Known hazard with optional mitigation |
| `` | `src`, `alt` | Image with caption (relative to session `assets/`) |
| `` | source as children | Mermaid diagram (`flow`, `sequence`, `state`, `gantt`, `er`, `mindmap`, `architecture`) |
For visuals beyond Mermaid, drop a custom component in `.synergy/sessions//_components/` and import it locally.
## Authoring rules
Four rules. Full text in [AGENTS.md](AGENTS.md).
1. **Components over markdown.** Use spec-kit components for structured content. If the shape doesn't exist, build a session-local component — don't fall back to raw markdown.
2. **CrossRefs, not links.** Spec-to-spec navigation uses ``. The validator catches dangling refs; raw markdown links it can't.
3. **Every session ships an `orchestrator.md`.** Plain markdown, not MDX, so it's readable in any tool. Describes dependency graph, parallel chunks, sub-agent vs agent-team strategy, verification gates.
4. **Validator is the gate.** `synergy validate` returns zero errors before a session is considered ready.
## Troubleshooting
**"vite binary not found" or "command not found"** — the plugin's workspace isn't built. Run `/synergy-setup`. If pnpm itself is missing, `corepack enable` or `npm i -g pnpm`.
**"port 4321 in use"** — another process owns the port. Run `/synergy-preview-stop` first; if a different program holds it, identify with `lsof -i :4321` and quit it before retrying.
**Validation fails on ``** — the target slug or heading anchor doesn't exist in the session. Either fix the `to=` value or add the heading. Anchors are GitHub-style: lowercase, spaces → `-`, special chars stripped.
## License & links
MIT. See [AGENTS.md](AGENTS.md) for spec-authoring rules, [CLAUDE.md](CLAUDE.md) for project conventions, [SYNERGY_PLAN.md](SYNERGY_PLAN.md) for the original design.