[refactor] spectra-archive SKILL.md exists in 3 copies (.claude/, .agents/, plugins/) — divergence risk (follow-up from #56)

[kiki830621]

Source

Surfaced during /idd-verify #56 round 1 (Codex F entry-risk + regression P3.9). Filed as follow-up from /idd-implement #56 Step 5.7.

Problem

spectra-archive skill exists in three places in this repo:

1. .claude/skills/spectra-archive/SKILL.md — the one we edited for feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56
2. .agents/skills/spectra-archive/SKILL.md — alternative skill directory
3. plugins/issue-driven-dev/.../spectra-skills/ — possibly bundled inside plugin

Only #1 was edited for #56's Implementation Complete auto-post feature. If the actual invocation entry resolves through copy #2 or #3, the change has zero effect.

Suggested

1. Identify canonical copy by tracing how /spectra-archive slash command resolves (likely .claude/skills/ for project-local skills)
2. Either sync all three copies OR delete duplicates with a single canonical source
3. Add a CI / pre-commit check to flag drift between copies

Priority

P3 — quality-of-life. #56's implementation is correct for .claude/skills/; copies #2 and #3 may serve different purposes (e.g. plugin distribution vs project-local) and require investigation.

Related

• Source: /idd-verify feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56 master report feat(spectra-archive): auto-post Implementation Complete to linked GitHub issue (#56) #92 (comment) (P3 [refactor] idd-list Step 5: needs-fix × PR state matrix 應展開,不該摺疊成單行 (verify follow-up from #13) #16)
• Related: feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56 spectra-archive auto-post Implementation Complete

---

Current Status

• Phase: closed
• Complexity: Plan
• Diagnosed at: 2026-05-20

[kiki830621]

Note from /idd-verify --pr 101 (#91 R1 verify, DA-1)

#91's verify surfaced a 4th spectra-archive copy beyond the 3 this issue enumerates:

4. .claude/commands/spectra/archive.md — the /spectra:archive command-file surface, wrapped in <!-- SPECTRA:START v1.0.2 --> … <!-- SPECTRA:END --> tool-managed markers (regenerated by the spectra CLI).

Observed divergence:

• .claude/commands/spectra/archive.md — 7-step version, no Step 0
• .claude/skills/spectra-archive/SKILL.md — 8-step version (feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56 added Step 7 "Post Implementation Complete" to the SKILL.md only); [refactor] spectra-archive SKILL.md missing Bootstrap TaskList (inconsistent with idd-* skills) (mid-plan tangential from #56) #91 added Step 0 Bootstrap to the SKILL.md only
• .agents/skills/spectra-archive/SKILL.md + plugins/issue-driven-dev/references/spectra-skills/spectra-archive/SKILL.md — the other 2 copies this issue lists

When this issue is worked, the canonical-copy resolution should distinguish:

• the command file is tool-regenerated — editing inside SPECTRA:START/END is fragile (next spectra CLI sync overwrites)
• the SKILL.md copies are hand-maintained (feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56 + [refactor] spectra-archive SKILL.md missing Bootstrap TaskList (inconsistent with idd-* skills) (mid-plan tangential from #56) #91 both edited .claude/skills/... directly and it stuck)

So "sync all copies" is not uniform — the command file can't be hand-synced durably. A CI/pre-commit drift check (this issue's suggestion 3) would need to treat the tool-managed file differently.

Source: PR #101 R1 verify Devil's Advocate finding DA-1.

[kiki830621]

Diagnosis

Type

refactor (3-copy divergence — canonical-copy identification + divergence elimination)

Root Cause / Analysis

Audit at diagnose time confirms the 3 copies exist as filed in the issue:

.claude/skills/spectra-archive/SKILL.md            (14865 bytes — edited for #56)
.agents/skills/spectra-archive/SKILL.md            (5694 bytes  — different size, OUT OF SYNC)
plugins/issue-driven-dev/references/spectra-skills/spectra-archive/SKILL.md  (reference copy)

diff -q confirms .claude/ and .agents/ already differ — drift is real, not theoretical. The plugins/.../references/spectra-skills/ directory contains a snapshot of multiple spectra-* skills (spectra-debug / spectra-discuss / spectra-audit / spectra-archive), suggesting it's a reference snapshot bundled with the IDD plugin (NOT an invocation target).

Resolution paths:

1. Canonical-copy identification — /spectra-archive slash command resolves via Claude Code's skill-loading order. .claude/skills/ is the project-local skills directory loaded by Claude Code; .agents/skills/ is likely a legacy or alternative skill directory (need investigation — may be agents.md compatibility layer). plugins/.../references/ is a static reference snapshot for docs.

2. Sync-or-delete decision — once canonical is identified:

   • .claude/skills/ IS the canonical (per /spectra-archive invocation testing) → make .agents/ a symlink OR delete it; plugins/.../references/ keeps as snapshot
   • Alternative: keep .agents/ as legacy + add note that .claude/ is authoritative

3. Drift prevention — once canonical resolved, add a CI / pre-commit check that warns when divergence appears between copies (or fails build if hard policy).

Impact

• .claude/skills/spectra-archive/SKILL.md — canonical (14865 bytes, has feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56 Implementation Complete auto-post feature)
• .agents/skills/spectra-archive/SKILL.md — 5694 bytes, OUT OF SYNC, missing feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56 feature
• plugins/issue-driven-dev/references/spectra-skills/spectra-archive/SKILL.md — reference snapshot, may or may not need sync
• Possibly other spectra-* skills in references/spectra-skills/ (audit / debug / discuss) may have same 3-copy structure — sister concern

Strategy

• Phase 1 (investigation): Empirically verify which copy Claude Code's /spectra-archive actually loads — invoke /spectra-archive --help or similar and trace resolution
• Phase 2 (decision): Pick disposition per identified canonical:
  • Option A: .claude/ canonical → delete .agents/ (after confirming it's not loaded), keep plugins/.../references/ as docs snapshot
  • Option B: .claude/ canonical → make .agents/ a symlink to .claude/
  • Option C: both .claude/ AND .agents/ are active load paths → resolve by syncing feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56 content from .claude/ to .agents/
• Phase 3 (sync content): Apply feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56 Implementation Complete auto-post feature to all canonical-active copies
• Phase 4 (drift prevention): NEW tests/check-spectra-archive-copies.sh or pre-commit hook that warns on divergence
• Phase 5 (sister-skill audit): Check references/spectra-skills/ other skills (audit / debug / discuss) for the same 3-copy pattern; consider filing sister issues if found

Complexity

Plan (decision-heavy investigation + multi-file resolution + drift prevention)

Layer P triggers:

• Decision-heavy with 2+ valid approaches — Phase 2 has 3 disposition options (delete vs symlink vs sync) with materially different ergonomics; the choice affects future contributors' editing workflow
• 2+ files have sequential dependency — Phase 1 investigation determines Phase 2 disposition; Phase 3 sync depends on Phase 2 choice
• Architectural decision with long-term maintenance implications — drift-prevention CI hook is the structural fix that defines how spectra-* skills are maintained going forward

Layer 2 check: skill files are internal to IDD plugin — no published API to future callers. Not Spectra.

Risks

• .agents/ may be loaded by some non-Claude-Code agent (e.g., agents.md consumers) — deleting could break unexpected callers
• plugins/.../references/spectra-skills/ snapshot may be referenced by other IDD docs — needs grep audit before any change
• Sister spectra-* skills (audit / debug / discuss) might have same divergence — Phase 5 could surface 3 more 3-copy issues

Residue

Sister-skill audit (Phase 5) is a candidate sister concern — IF references/spectra-skills/ other skills have the same 3-copy pattern, they each warrant their own sister-bug issue. Plan tier deliberation should surface this for explicit user decision.

Vagueness Pre-check

• V1: 2 — Strategy bullets enumerate concrete files + ordered investigation/implementation steps
• V4: 2 — Issue body's "## Expected" / "## Suggested fix" gives explicit completion criteria
• Triggered: no — both axes ≤ 3

[kiki830621]

Phase 1 investigation update (scope revision)

Diagnosed at /idd-diagnose recommended deleting .agents/skills/ as legacy. Investigation refutes that — .agents/skills/ is LIVE:

$ grep -rln '\.agents/skills' openspec/specs/
openspec/specs/routing-vagueness-layer/spec.md
openspec/specs/idd-all-chain/spec.md
openspec/specs/idd-spawn-manifest/spec.md
openspec/specs/idd-orchestrator-modes/spec.md

4 openspec specs reference .agents/skills/spectra-*/SKILL.md paths as Spectra-tier dependencies — likely the Spectra CLI / agents.md-format load path. Deleting would break these spec references.

Sister-skill divergence audit — all 8 spectra-* skills diverge between .claude/ and .agents/:

Skill	.claude/ size	.agents/ size	Drift
spectra-archive	14865	5694	HUGE — #56 feature only in .claude/
spectra-audit	5544	9709	HUGE — opposite direction
spectra-discuss	14667	14667	small text drift
spectra-propose	18177	18144	small text drift
spectra-apply	17971	17971	small text drift
spectra-ingest	14723	14633	small text drift
spectra-debug	4541	4541	small text drift
spectra-commit	8721	8721	small text drift

Revised disposition for this issue scope:

• Sync .agents/skills/spectra-archive/SKILL.md from .claude/ — apply feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56's Implementation Complete auto-post feature + Step 0 Bootstrap. This closes the feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56 "actual entry point" risk that originally surfaced this issue.
• plugins/issue-driven-dev/references/spectra-skills/spectra-archive/SKILL.md — no markdown cross-refs found → safe to update OR leave as historical snapshot. Per feedback_lead_minimal — leave as snapshot (no callers, low cleanup ROI).
• Sister divergences (7 other spectra- skills)* — beyond this issue's stated scope (which is spectra-archive). Filed for follow-up as systematic sister-skill audit. Each may have its own feature: spectra-apply auto-post Implementation Complete to GitHub issue (resolve /idd-close supersession friction) #56-equivalent feature missing OR may just be cosmetic drift.

Drift-prevention CI check (Phase 4 of original strategy) — deferred. Adding a CI hook adds policy surface; better to fix the immediate divergence first and observe if drift recurs naturally before instrumenting prevention.

[kiki830621]

Implementation Complete

Checklist

• Strategy bullets shipped
• Commit: c3b9045 (cluster branch idd/chain-multi-4afc6a91-refactor-spectra-archive-skill-md-exists)
• PR opened: chain (multi-root): 3 issues — spectra-archive sync + cluster glob + pasted-image cache #115 (cluster, all 3 sister issues)
• CHANGELOG v2.70.0 entry + plugin.json version bump

Scope shipped

Synced .agents/skills/spectra-archive/SKILL.md from .claude/ — both LIVE load paths now carry v1.3+ Implementation Complete auto-post feature from #56. Investigation refuted diagnose-time recommendation to delete .agents/ (4 openspec specs reference .agents/skills/ paths). Sister-skill divergences for 7 other spectra-* skills documented in audit comment as candidates for separate follow-up.

Notes

• Per cluster discipline: per-issue verify findings will be partitioned in the cluster verify report at PR chain (multi-root): 3 issues — spectra-archive sync + cluster glob + pasted-image cache #115

[kiki830621]

Verify (PR mode, cluster) — verify-gated PASS for this issue's portion of PR #115. 0 blocking findings post-fix; 3-AI + Codex ensemble PASS (requirements process gap recorded — coverage substituted via Codex + DA). Cluster ready to merge → /idd-close per issue.

[kiki830621]

Closing Summary

Problem

spectra-archive skill existed in 3 copies in the repo (.claude/skills/, .agents/skills/, plugins/.../references/spectra-skills/). #56's Implementation Complete auto-post feature was applied only to the .claude/ copy. If the actual /spectra-archive invocation resolves through .agents/ or plugins/.../references/ instead, the #56 change had zero effect. Surfaced during /idd-verify #56 round 1 (Codex F entry-risk + regression P3.9).

Root Cause

Skill files exist at multiple paths to support multiple agent runtimes:

• .claude/skills/ — Claude Code project-local skill load path
• .agents/skills/ — agents.md-format / Spectra CLI load path (LIVE — referenced by 4 openspec specs as Spectra-tier dependencies)
• plugins/.../references/spectra-skills/ — historical reference snapshot bundled with IDD plugin

Original diagnosis recommended deleting .agents/ as legacy. Investigation refuted this: grep -rln '\.agents/skills' openspec/specs/ returned 4 specs (routing-vagueness-layer, idd-all-chain, idd-spawn-manifest, idd-orchestrator-modes) that reference .agents/skills/spectra-*/SKILL.md paths. Deleting would break spec references.

Solution

Commit c3b9045 (PR #115):

• Synced .agents/skills/spectra-archive/SKILL.md from .claude/skills/spectra-archive/SKILL.md via cp — both 14865 bytes, byte-identical post-fix (logic empirically confirmed diff -q clean, MD5-equal)
• Both LIVE load paths now carry v1.3+ Implementation Complete auto-post feature + Step 0 Bootstrap discipline

Out of scope (documented in scope-revision audit comment posted to #93):

• plugins/.../references/spectra-skills/spectra-archive/SKILL.md — no markdown cross-refs found via repo grep; left as historical snapshot per feedback_lead_minimal
• 7 sister spectra-* skills (audit / discuss / propose / apply / ingest / debug / commit) ALSO diverge between .claude/ and .agents/ — drift matrix documented in audit comment
• Drift-prevention CI hook deferred

DA-1 finding fix (commit d63575a): original CHANGELOG wording "filed for separate follow-up as needed" was misleading (no sister-skill issues actually filed). Softened to "drift documented as observation; separate issues will be filed if specific divergence causes user-visible friction".

Verification

3-AI verify ensemble (PR #115 cluster mode) + Codex — verify-gated PASS post-fix. Master: #115 (comment)

Logic + DA + Codex all independently confirmed sync correctness. Requirements reviewer process gap recorded (file cross-contaminated from different verify session).

Changes

• Squash merge: f5afb93 (PR chain (multi-root): 3 issues — spectra-archive sync + cluster glob + pasted-image cache #115)
• .agents/skills/spectra-archive/SKILL.md synced from .claude/
• Shared CHANGELOG.md v2.70.0 + plugin.json 2.69.0 → 2.70.0

Residue

Sister-skill drift across 7 spectra- skills* — documented in #93 audit comment as observation. Per lead-minimal: defer filing sister issues until specific divergence causes user-visible friction. If any sister-skill divergence triggers a future #56-equivalent "wrong copy edited" incident, file then.

Drift-prevention CI hook — deferred. Adding policy surface (pre-commit / CI check) before drift recurs naturally would be premature.