AGENTS.md — Synergy planning and review

Rules and conventions for any agent (Claude Code, Codex, or otherwise) that authors or edits Synergy artifacts. Cross-host file — kept in sync with CLAUDE.md.

What Synergy is

A planning and guided-review system. Agents generate cross-referenced MDX documents in .synergy/sessions/<session-name>/ or prepare immutable code-review artifacts in .synergy/reviews/<workspace>/, rendered by the same Vite + React preview at the verified origin returned by synergy preview status --json. Specification sessions keep a separate orchestrator.md that tells the implementing agent how to execute the work.

Hard rules

1. Session location. All spec content lives in .synergy/sessions/<YYYY-MM-DD-<slug>>/. Never write spec files anywhere else in the consumer project.
2. Components over markdown. Prefer spec-kit components (<Status>, <Phase>, <Timeline>, <SubSpec>, <CrossRef>, <AgentAllocation>, <OpenQuestion>, <Risk>, <Mockup>, <Chart>, <Team>, <Reviewer>) over ad-hoc markdown for structured content.
3. Build, don't degrade. When the structure you need doesn't exist in spec-kit, create a session-local component in _components/ rather than falling back to raw markdown.
4. CrossRefs are mandatory. Every spec-to-spec link uses <CrossRef to="<slug>" /> or <CrossRef to="<slug>#<anchor>" />. Phase refs use <CrossRef to="phases/<slug>" /> — the slug, never the numeric prefix. Do not write [link](other.mdx) style markdown links — the validator can't enforce those.
5. Phases are folders. Every phase lives in phases/<NN>-<slug>/ with a required spec.mdx and an optional orchestrator.md. Inline <Phase> blocks are summary cards in 02-implementation.mdx, not the phase itself.
6. Orchestrator file is required. Every session has a root orchestrator.md (plain markdown, not MDX) describing dependency graph, parallel chunks, agent strategy, verification gates. Per-phase orchestrators are optional but recommended for multi-task phases.
7. Validator is the gate. A session is not "ready" until synergy validate <session> returns zero errors. Warnings are acceptable but must be reviewed.
8. Charts. Default to <Chart> (Mermaid). When Mermaid can't express what you need, write a session-local chart component in _components/ using any library (recharts, visx, react-flow, …).
9. Preview lifecycle. The preview server prefers port 4321 and may select an alternate. Never bypass the CLI or infer its origin — use synergy preview start|stop|status and consume the verified runtime status.
10. Required overview headings. 00-overview.mdx must contain ## Summary and ## Goals. The validator errors out otherwise. Other sections are optional.

Session structure

.synergy/sessions/<YYYY-MM-DD-slug>/
├── 00-overview.mdx          required: ## Summary + ## Goals at minimum
├── 01-architecture.mdx      optional: system shape, diagrams
├── 02-implementation.mdx    optional: timeline, agent allocation, phase index
├── NN-<custom>.mdx          optional: extra sub-specs, keep NN ordered
├── orchestrator.md          required: root-level implementation playbook
├── _components/             optional: session-local React/MDX components
├── assets/                  optional: images, mockups
└── phases/                  optional: omit for non-phased specs
    ├── 01-<slug>/
    │   ├── spec.mdx         required if folder exists
    │   └── orchestrator.md  optional; warned-on-miss for multi-task phases
    ├── 02-<slug>/
    └── ...

Minimal session: just orchestrator.md + 00-overview.mdx. Everything else is optional.

Generating a session

Spec authoring is a skill, not a CLI command. To create a new session, invoke the synergy:create-spec skill (or run /synergy-spec "<title>" in Claude Code, which dispatches to the skill).

The skill:

1. Reasons about scope (tiny note, single-phase, or multi-phase).
2. Picks a name (YYYY-MM-DD-<slug>) with a 6-char hash suffix on collision.
3. Scaffolds the session from templates that ship inside the skill (skills/synergy/create-spec/templates/).
4. Creates phases/<NN>-<slug>/ folders for each phase it decided on.
5. Starts the preview server via synergy preview start (idempotent).
6. Prints the session URL using the origin returned by the preview runtime.

Editing or extending an existing session uses the synergy:spec-authoring skill, which covers adding/inserting/renaming/removing phase folders without breaking cross-refs.

Editing iterations

The preview hot-reloads on every save. Edit the MDX, watch the browser refresh, take user feedback, repeat. Add or remove .mdx files in the session and the virtual session index rebuilds — the page does a full reload automatically.

Orchestrator template

Every orchestrator.md has these sections:

# Orchestrator — <title>

> Session: <name>. Type: <feature|refactor|project>.

## Overview
One paragraph. What, why, success criteria.

## Dependency graph
ASCII or Mermaid representation of phase ordering. Same-line items can run in parallel.

## Parallel chunks
Explicit list of which phases can be sub-agent-parallel vs sequential.

## Agent strategy
- Sub-agents for: <bounded, well-specified tasks>
- Agent team for: <cross-cutting, exploratory work>
- Human in the loop at: <phase boundaries>

## Verification gates
- After Phase N: <command to run, criteria to meet>

## How to invoke
"Implement the plan in @.synergy/sessions/<name>/ — start with orchestrator.md."

Cross-reference syntax

Phase refs use the slug only — never the numeric prefix. phases/01-core is invalid. The numeric prefix orders folders on disk; the slug is the stable identifier. Renumbering phases (e.g. inserting 02-warmup between 01-foundation and what becomes 03-core) does not break refs that use the slug form.

Legacy phase refs of the form 02-implementation#phase-2 still resolve but the validator warns and asks you to migrate to phases/<slug>.

Anchors are GitHub-style: lowercase, spaces → -, special chars stripped, deduped per file.

Component cheat sheet

Inline editing and feedback (v2)

The preview runtime adds an edit and feedback layer on top of the read-only v1 preview. Discover its current origin with synergy preview status --json; agents interact with it via the feedback skill, while the browser UI is for human reviewers.

• Apply / Discard buffer. Prose blocks are contentEditable in the browser. Every edit is held in memory until the human clicks Apply (flushes to the MDX file on disk) or Discard (reverts). No auto-save. Phase status dropdowns use the same buffer.
• Selection comments. A human selects text in the preview, clicks "+", leaves a note. Each comment is a markdown file at .synergy/feedback/<session>/<id>.md with YAML frontmatter carrying both line/col coordinates and a before+selected+after context string for drift-tolerant re-anchoring.
• Diff view. Top-toolbar toggle. Highlights committed and uncommitted changes since the human's last "Mark as reviewed". Review state persists to .synergy/review-state.json.
• Pull-based handoff. When the human runs /synergy-feedback, the synergy:address-feedback skill reads .synergy/active-session, loads all status: open comment files, edits the spec at each anchor, and PATCHes each comment to resolved or rejected. Run synergy validate <session> before declaring done. With --wait, the skill's Live wait mode blocks on synergy feedback wait <session> and loops until the human clicks Done reviewing (see CLAUDE.md "Live feedback loop").
• Gitignored files. active-session and review-state.json are per-machine state — do not commit them. sessions/ and feedback/ remain tracked (they are spec content).

CLI surface

The CLI handles deterministic process, execution-state, and review-artifact operations — see CLAUDE.md "Commands" for the authoritative subcommands. Spec authoring and repository-aware review analysis live in shared skills; there is no synergy spec command.

Guided code reviews

Review is independent from MDX specification sessions. Invoke the cross-host synergy:review skill (or Claude Code's thin /synergy-review command) for a GitHub PR, staged changes, unstaged changes, or a bounded current-code scope. The skill delegates capture, validation, reconciliation, persistence, freshness, and readiness to synergy review ...; agents own only repository-aware grouping, scoped section selection, concise descriptions, and answers.

Review artifacts live in gitignored .synergy/reviews/<workspace>/revisions/<revision>/ and render at /r/<workspace>/<revision>. .synergy/active-review.json is the per-machine browser pointer. Never hand-edit those JSON artifacts. An exact workspace@revision never advances; refreshing a workspace creates or resumes its current immutable revision and carries coverage forward only through deterministic reconciliation.

For browser questions, run synergy review wait <workspace@revision> --for 15m in the foreground, answer through synergy review answer, and wait again. Never detach the wait, invent context across revisions, analyze ignored untracked files, or mutate application code unless the user separately asks for implementation.

Preview design system

The preview app's visual language ("Ember & Graphite" - warm copper accent on warm graphite/paper neutrals, Space Grotesk + Inter + JetBrains Mono) is token-driven. packages/preview/src/theme.css is the single token source; docs/design-system.md documents it. When touching preview or spec-kit CSS, consume --syn-* tokens (or the --sk-* aliases) - never hardcode palette hex values in component rules.

Don'ts

• Don't co-locate session content in the consumer's source tree. Always .synergy/sessions/.
• Don't write raw markdown links between specs.
• Don't bypass validation by silencing errors.
• Don't bundle implementation code in the spec — it describes work, agents do work.
• Don't edit orchestrator.md to be MDX-flavored — it must stay plain markdown for CLI legibility.
• Don't treat the preferred port 4321 as the runtime authority; consume the verified origin.
• Don't reference phases by numeric prefix in CrossRefs. The slug is the identifier; the prefix is just sort order.
• Don't try to add a synergy spec CLI command. Authoring is a skill.

Maintaining this file

Keep this file for knowledge useful to almost every future agent session in this project. Do not repeat what the codebase already shows; point to the authoritative file or command instead. Prefer rewriting or pruning existing entries over appending new ones. When updating this file, preserve this bar for all agents and keep entries concise.