Clay GoodandClaude Opus 5 92fb72d1dc fix(workflows): create the main spec when a capability is new (#1701) ...

* fix(workflows): create the main spec when a capability is new

The agent-driven archive workflow told agents to "compare each delta spec
with its corresponding main spec" and said nothing about the case where
that main spec does not exist yet. Comparing against nothing reads as
"already synced", so the agent took the archive branch and the new
capability's main spec was never written — the change landed in
changes/archive/ with openspec/specs/ still empty.

`openspec archive` already handles this: buildUpdatedSpec creates the spec
from the delta's ADDED requirements, rejects MODIFIED/RENAMED with "only
ADDED requirements are allowed for new specs", and warns past REMOVED. The
guidance now says the same thing, so the agent path and the CLI path agree:

- archive-change: a missing main spec counts as changes needed and is named
  in the summary as a spec the sync will create — never as already synced.
- sync-specs: MODIFIED and RENAMED have no requirement to act on when the
  main spec is absent, so the sync stops and reports rather than inventing
  one; REMOVED is skipped with a warning.

Guidance text only — no CLI, parser, or archive behavior changes.

Closes #1222
Closes #1264

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(sync): never create a main spec with nothing to put in it

CodeRabbit caught a gap in the previous commit: step 4b now tells the agent
a REMOVED-only delta has nothing to remove, but step 4d still read as
"create the main spec if the capability doesn't exist yet" unconditionally.
Following both would write a spec whose `## Requirements` section is empty.

Verified against the CLI on a REMOVED-only delta targeting a capability with
no main spec:

    Specs to update:
      parking: create
    ⚠️  Warning: parking - 1 REMOVED requirement(s) ignored for new spec.
    Validation errors in rebuilt spec for parking (will not write changes):
      ✗ Spec must have at least one requirement
    Aborted. No files were changed.

So step 4d is now gated on the delta having ADDED requirements to seed the
spec with, and says what the CLI reports when it does not.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs: define "main spec" and close the no-ADDED archive loop

Hardening pass over the two fixes in this branch.

Guidance: the archive step's verification pass re-runs the same comparison
the fix touched, so a delta that can create nothing — no ADDED requirements,
no main spec to merge into — would have been reported as "still needs sync"
after a sync that correctly created nothing, and an agent could loop on it.
That case now short-circuits with the reason, matching `openspec archive`,
which refuses it with "Spec must have at least one requirement".

Docs: the glossary defined "delta spec" but never "main spec", which is
half of #1647's terminology complaint. It now defines the term and says
that for a new capability the main spec is created by the archive rather
than written up front; concepts.md says the same in the delta-section table
and the archive process. The docs site generates from docs/ at build time,
so no website files change.

Changeset rewritten in the house style (prose, no commit header; the
changelog-github action supplies attribution) and renamed descriptively.

All three CLI branches this guidance describes were verified end to end:
ADDED against a greenfield repo creates the spec and carries its Purpose;
MODIFIED reports "target spec does not exist; only ADDED requirements are
allowed for new specs"; REMOVED-only aborts with "Spec must have at least
one requirement" and writes nothing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(glossary): a standalone sync creates the main spec too

The "Main spec" entry said the spec is created "by the archive", but the
"Sync" entry two sections down says /opsx:sync creates it as well, without
archiving — and specs-sync-skill's "New capability spec" scenario is the
sync's own behavior. Names both paths so the two entries agree.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(workflows): clarify removed deltas for missing specs

* fix(workflows): preserve explicitly retired missing specs

* fix(archive): preserve explicit skip-sync choice for blocked deltas

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

2026-09-16 15:47:51 +00:00

..

changes

…

explorations

…

initiatives/context-store-and-initiatives

…

specs

fix(workflows): create the main spec when a capability is new (#1701)

2026-09-16 15:47:51 +00:00

work

…

config.yaml

…