feat(unic-spec-review): scaffold plugin with PRD and ADRs

.claude-plugin/marketplace.json

@@ -24,6 +24,10 @@
     {
       "name": "unic-pr-review",
       "source": "./apps/claude-code/unic-pr-review"
+    },
+    {
+      "name": "unic-spec-review",
+      "source": "./apps/claude-code/unic-spec-review"
     }
   ]
 }

.github/workflows/ci.yml

@@ -25,6 +25,7 @@ jobs:
     outputs:
       pr-review: ${{ steps.filter.outputs.pr-review }}
       unic-pr-review: ${{ steps.filter.outputs.unic-pr-review }}
+      unic-spec-review: ${{ steps.filter.outputs.unic-spec-review }}
       auto-format: ${{ steps.filter.outputs.auto-format }}
       unic-confluence: ${{ steps.filter.outputs.unic-confluence }}
       release-tools: ${{ steps.filter.outputs.release-tools }}
@@ -39,6 +40,8 @@ jobs:
               - 'apps/claude-code/pr-review/**'
             unic-pr-review:
               - 'apps/claude-code/unic-pr-review/**'
+            unic-spec-review:
+              - 'apps/claude-code/unic-spec-review/**'
             auto-format:
               - 'apps/claude-code/auto-format/**'
             unic-confluence:
@@ -57,7 +60,8 @@ jobs:
       needs.changes.outputs.release-tools == 'true' ||
       needs.changes.outputs.unic-archon-dlc == 'true' ||
       needs.changes.outputs.pr-review == 'true' ||
-      needs.changes.outputs.unic-pr-review == 'true'
+      needs.changes.outputs.unic-pr-review == 'true' ||
+      needs.changes.outputs.unic-spec-review == 'true'
     strategy:
       fail-fast: false
       matrix:
@@ -76,6 +80,8 @@ jobs:
             changed: ${{ needs.changes.outputs.pr-review }}
           - name: unic-pr-review
             changed: ${{ needs.changes.outputs.unic-pr-review }}
+          - name: unic-spec-review
+            changed: ${{ needs.changes.outputs.unic-spec-review }}
         exclude:
           - package:
               changed: 'false'

.github/workflows/release.yml

@@ -54,3 +54,4 @@ jobs:
           tag_if_changed "apps/claude-code/unic-confluence"
           tag_if_changed "apps/claude-code/unic-archon-dlc"
           tag_if_changed "apps/claude-code/unic-pr-review"
+          tag_if_changed "apps/claude-code/unic-spec-review"

AGENTS.md

@@ -15,7 +15,8 @@ apps/
 │   ├── auto-format/
 │   ├── unic-confluence/
 │   ├── unic-archon-dlc/
-│   └── unic-pr-review/
+│   ├── unic-pr-review/
+│   └── unic-spec-review/
 └── copilot/                  # GitHub Copilot plugins (future)
 packages/
 ├── biome-config/             # @unic/biome-config
@@ -80,6 +81,8 @@ Plugins are versioned independently. `plugin.json` is the source of truth. Use `
 
 Tag scheme: `<plugin-name>@<version>` (e.g. `auto-format@0.5.5`).
 
+**CHANGELOG version headers** must use the format `## [X.Y.Z] — YYYY-MM-DD` (em dash, then ISO date). `pnpm bump` writes this format and `verify:changelog` (in `packages/release-tools`) structurally enforces ` — YYYY-MM-DD` on every versioned header. Do not change the separator or the date format: CI and the release flow depend on it.
+
 ## Conventional commits
 
 Use package scope: `feat(auto-format): …`, `fix(pr-review): …`, `chore(release-tools): …`, `chore(unic-archon-dlc): …`, `feat(unic-pr-review): …`.

CONTEXT-MAP.md

@@ -2,17 +2,18 @@
 
 ## Shared vocabulary
 
-- [Monorepo](./CONTEXT.md) — Plugin, Workspace Package, Release, Feature, Feature Runner, Consumer
+- [Monorepo](./CONTEXT.md): Plugin, Workspace Package, Release, Feature, Feature Runner, Consumer
 
 ## Plugin contexts
 
 Each context maps to an `app:` area label on the issue tracker (see [Area labels](#area-labels)).
 
-- [auto-format](./apps/claude-code/auto-format/CONTEXT.md) — formatting automation hook for Claude Code (`app:auto-format`)
-- [pr-review](./apps/claude-code/pr-review/CONTEXT.md) — **DEPRECATED (v1)**, superseded by `unic-pr-review`; frozen and hook-protected against edits, do not develop here or port anything out of it (`app:pr-review`)
-- [unic-confluence](./apps/claude-code/unic-confluence/CONTEXT.md) — Markdown-to-Confluence publishing command (`app:unic-confluence`)
-- [unic-archon-dlc](./apps/claude-code/unic-archon-dlc/CONTEXT.md) — Archon-powered AI development lifecycle DLC (`app:unic-archon-dlc`)
-- [unic-pr-review](./apps/claude-code/unic-pr-review/CONTEXT.md) — AI-powered PR review with intent checking and Confidence-scored Findings (`app:unic-pr-review`)
+- [auto-format](./apps/claude-code/auto-format/CONTEXT.md): formatting automation hook for Claude Code (`app:auto-format`)
+- [pr-review](./apps/claude-code/pr-review/CONTEXT.md): **DEPRECATED (v1)**, superseded by `unic-pr-review`; frozen and hook-protected against edits, do not develop here or port anything out of it (`app:pr-review`)
+- [unic-confluence](./apps/claude-code/unic-confluence/CONTEXT.md): Markdown-to-Confluence publishing command (`app:unic-confluence`)
+- [unic-archon-dlc](./apps/claude-code/unic-archon-dlc/CONTEXT.md): Archon-powered AI development lifecycle DLC (`app:unic-archon-dlc`)
+- [unic-pr-review](./apps/claude-code/unic-pr-review/CONTEXT.md): AI-powered PR review with intent checking and Confidence-scored Findings (`app:unic-pr-review`)
+- [unic-spec-review](./apps/claude-code/unic-spec-review/CONTEXT.md): adversarial review of web specifications across Confluence, Figma, and the live system (`app:unic-spec-review`)
 
 ## Workspace packages
 
@@ -35,7 +36,7 @@ This tier is a repo convention: hand-applied and maintained here, not generated
 ## Relationships
 
 - All Plugin contexts share the vocabulary defined in the monorepo context
-- **auto-format**, **pr-review**, **unic-archon-dlc**, and **unic-pr-review** are Claude Code Plugins with no runtime dependencies on each other
+- **auto-format**, **pr-review**, **unic-archon-dlc**, **unic-pr-review**, and **unic-spec-review** are Claude Code Plugins with no runtime dependencies on each other (`unic-spec-review` vendors shared code from `unic-pr-review` rather than importing it)
 - **unic-confluence** can be installed as a git dependency for use outside Claude Code.
 - **pr-review** has a soft dependency on the `pr-review-toolkit` plugin from `anthropics/claude-plugins-official`
 - **unic-archon-dlc** requires the Archon workflow engine (version ≥ 0.10) in the target project; it has no runtime dependencies on any other plugin in this repo

apps/claude-code/unic-spec-review/.claude-plugin/marketplace.json

@@ -0,0 +1,27 @@
+{
+  "metadata": {
+    "description": "Adversarial review of web specifications across Confluence, Figma, and the live system",
+    "homepage": "https://github.com/unic/unic-agents-plugins"
+  },
+  "name": "unic-spec-review",
+  "owner": {
+    "name": "Unic AG"
+  },
+  "plugins": [
+    {
+      "author": {
+        "name": "Unic AG"
+      },
+      "category": "productivity",
+      "description": "Adversarial review of web specifications across Confluence pages & comments, Figma designs, and the live system. Produces Confidence-scored, Six-Hats-tagged Findings with an interactive Approval Loop that posts selected comments back to Confluence.",
+      "displayName": "Unic Spec Review",
+      "homepage": "https://github.com/unic/unic-agents-plugins",
+      "keywords": ["spec-review", "confluence", "figma", "adversarial-review", "six-hats", "unic"],
+      "license": "LGPL-3.0-or-later",
+      "name": "unic-spec-review",
+      "source": "./",
+      "tags": ["productivity", "quality"],
+      "version": "0.1.0"
+    }
+  ]
+}

apps/claude-code/unic-spec-review/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "author": {
+    "name": "Unic AG",
+    "url": "https://www.unic.com"
+  },
+  "commands": ["./commands/review-spec.md", "./commands/spec-doctor.md", "./commands/setup-confluence.md"],
+  "description": "Adversarial review of web specifications across Confluence pages & comments, Figma designs, and the live system. Produces Confidence-scored, Six-Hats-tagged Findings with an interactive Approval Loop that posts selected comments back to Confluence.",
+  "homepage": "https://github.com/unic/unic-agents-plugins",
+  "keywords": ["spec-review", "confluence", "figma", "adversarial-review", "six-hats", "unic"],
+  "license": "LGPL-3.0-or-later",
+  "name": "unic-spec-review",
+  "version": "0.1.0"
+}

apps/claude-code/unic-spec-review/.gitignore

@@ -0,0 +1,116 @@
+node_modules/
+dist/
+*.local.*
+*.local
+pnpm-debug.log*
+
+# Ralph
+.ralph/
+.agents/scratchpad/
+
+# Visual Studio Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+!*.code-workspace
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+# VSCODE custom
+.history
+
+# Macos
+
+# General
+.DS_Store
+.localized
+__MACOSX/
+.AppleDouble
+.LSOverride
+Icon[
+]
+
+# Resource forks
+._*
+
+# Files and directories that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+.com.apple.timemachine.supported
+.PKInstallSandboxManager
+.PKInstallSandboxManager-SystemSoftware
+.hotfiles.btree
+.vol
+.file
+.disk_label*
+lost+found
+.HFS+ Private Directory Data[
+]
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# Mac OS 6 to 9
+Desktop DB
+Desktop DF
+TheFindByContentFolder
+TheVolumeSettingsFolder
+.FBCIndex
+.FBCSemaphoreFile
+.FBCLockFolder
+
+# Quota system
+.quota.group
+.quota.user
+.quota.ops.group
+.quota.ops.user
+
+# TimeMachine
+Backups.backupdb
+.MobileBackups
+.MobileBackups.trash
+MobileBackups.trash
+tmbootpicker.efi
+
+# Windows
+
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# Spec-review reports (gitignored review artifacts)
+.spec-review/

apps/claude-code/unic-spec-review/AGENTS.md

@@ -0,0 +1,47 @@
+# AGENTS.md · unic-spec-review
+
+Guidance for any AI agent working inside this Plugin directory. `CLAUDE.md` in this directory is a symlink to this file.
+
+## What this Plugin is
+
+`unic-spec-review` is a Claude Code Plugin in the [`unic-agents-plugins`](../../../AGENTS.md) monorepo. It runs an adversarial review of web specifications across four sources (Confluence pages & comments, Figma designs via the Dev Mode MCP, the live production system via the Playwright MCP, and the local repo) and emits Confidence-scored, Six-Hats-tagged Findings. An interactive Approval Loop, gated behind `--post`, publishes selected Findings as Confluence comments.
+
+> Status: scaffolding only. The command/agent logic is specified in the PRD under `docs/issues/` and not yet implemented.
+
+## Where to start
+
+Root docs (monorepo-wide conventions: pnpm scripts, Gitflow, SemVer, Conventional Commits, code conventions, LICENSE policy, cross-platform requirement):
+
+- [Root AGENTS.md](../../../AGENTS.md) is the source of truth for cross-cutting rules
+- [Root CONTEXT-MAP.md](../../../CONTEXT-MAP.md) indexes all bounded contexts in the repo
+- [Root docs/adr/](../../../docs/adr/) holds monorepo-wide architecture decisions
+
+This Plugin's own decisions:
+
+- [Plugin docs/adr/](docs/adr/): ADRs 0001 to 0004 (vendoring/self-containment, similarity dedup, Six-Hats lens, inline-anchored comments) and a README index
+- [CONTEXT.md](CONTEXT.md): domain vocabulary for this bounded context
+
+## Design (locked via grilling; see [PRD](docs/issues/unic-spec-review/PRD.md))
+
+- **Home:** standalone plugin. Commands `/review-spec` (main), `/spec-doctor` (preflight), `/setup-confluence` (credential wizard).
+- **Self-containment (hard requirement):** installable and usable on its own, with no runtime or setup dependency on `unic-pr-review` or `unic-confluence`. Ships its own `/setup-confluence` wizard and vendored credential handling. Duplication across plugins is accepted as the price of self-containment.
+- **Reuse by vendoring:** copy `atlassian-fetch.mjs`, `credentials.mjs`, and the `setup-confluence` wizard from `unic-pr-review` (plugins ship independently, so copy rather than cross-import). Extend `atlassian-fetch` with Confluence comment read + write. Credentials use the shared `~/.unic-confluence.json` convention (or `CONFLUENCE_*` env vars): a shared credential store, not a plugin coupling, so a user with both plugins configures Confluence once.
+- **Sources:** Confluence (pages + comments), Figma (Dev Mode MCP), live prod (Playwright MCP), local repo. MCPs are runtime-discovered; fail loud if absent.
+- **Review engine:** parallel multi-agent. Black-hat core = 8 dimension agents (Gaps, Ambiguity, Spec↔Design, Spec↔Live, Internal-consistency, Testability, Feasibility, NFR); plus Green (alternatives), Yellow (value), Red (UX reaction); White folded into Gaps+Testability; Blue = orchestrator/synthesis. Every Finding is hat-tagged + Confidence-scored.
+- **Landscape Brief:** the tech landscape is detected from the repo at runtime (never hardcoded) plus user-declared out-of-repo systems; computed once and injected into Testability, Feasibility, Spec↔Live, NFR.
+- **Output:** timestamped markdown report (`.spec-review/`, gitignored) + conversational ranked triage.
+- **Posting:** inline-anchored Confluence comment (v2 API), footer fallback; visible attribution footer (no hidden marker). De-dup by content-similarity vs all existing comments (own + other users' + human) + human tiebreak in the loop.
+- **Write safety:** bare run = read-only. `--post` enables the Approval Loop. Invariant: `--post` makes posting _possible_, never automatic, and stays cancellable at every step, including a final "post none" exit.
+
+## Commands
+
+```sh
+pnpm bump <patch|minor|major>   # bump plugin.json version + promote CHANGELOG
+pnpm sync-version               # mirror plugin.json version into marketplace.json + package.json
+pnpm tag                        # create the unic-spec-review@<version> git tag locally
+pnpm verify:changelog           # check CHANGELOG entry for the current version
+```
+
+> `pnpm test` and `pnpm typecheck` (plus `tsconfig.json` and the `scripts/`/`tests/` dirs) will be added back once the first `.mjs` script is vendored during implementation. The plugin is command-only at scaffold time.
+
+Monorepo-wide commands (`pnpm install`, `pnpm check`, `pnpm format`, `pnpm ci:check`) are documented in the [root AGENTS.md](../../../AGENTS.md).

apps/claude-code/unic-spec-review/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Breaking
+
+- (none)
+
+### Added
+
+- (none)
+
+### Fixed
+
+- (none)
+
+## [0.1.0] — 2026-06-05
+
+### Added
+
+- Scaffold the unic-spec-review plugin: `/review-spec`, `/spec-doctor`, and `/setup-confluence` command stubs; PRD (#200); ADRs 0001 to 0004; `CONTEXT.md` domain vocabulary; `app:unic-spec-review` area label; CI and release-workflow registration. Command and agent logic pending implementation.

apps/claude-code/unic-spec-review/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

apps/claude-code/unic-spec-review/CONTEXT.md

@@ -0,0 +1,26 @@
+# CONTEXT · unic-spec-review
+
+Domain vocabulary for the `unic-spec-review` plugin. This is a single bounded context inside the [monorepo context map](../../../CONTEXT-MAP.md).
+
+> Status: scaffolding. The behaviour behind these terms is specified in [`docs/issues/unic-spec-review/PRD.md`](docs/issues/unic-spec-review/PRD.md) and not yet implemented.
+
+## Vocabulary
+
+- **Spec (Specification):** the web-specification under review. Usually a Confluence parent page plus child pages, but not exclusively.
+- **Source:** one of the four inputs a review reads from: Confluence (pages and comments), Figma (designs and annotations, via the Dev Mode MCP), the Live System (production, via the Playwright MCP), and the local Repo.
+- **Reviewer:** the person running `/review-spec`. May be the spec author or someone else.
+- **Review:** a single run of `/review-spec` over a set of Sources.
+- **Dimension:** one technical aspect a review agent inspects (Gaps, Ambiguity, Spec-versus-Design, Spec-versus-Live, Internal-consistency, Testability, Feasibility, Non-functional).
+- **Hat:** a Six-Thinking-Hats perspective tag carried by every Finding. Black is the critique core (the Dimensions); Green is alternatives; Yellow is value and justification; Red is user reaction; White is facts (folded into Gaps and Testability); Blue is the orchestrator and synthesiser.
+- **Finding:** a single reviewed issue. Carries a Dimension, a Hat, a Confidence Score, a Severity, and (where possible) an anchor into the spec text.
+- **Confidence Score:** how sure the agent is that a Finding is real, used to rank and triage.
+- **Severity:** how impactful a Finding is if real, used alongside Confidence to rank.
+- **Landscape Brief:** the technology landscape detected from the repo at runtime (stack, test setup, tooling, reachable-prod flag) plus declared adjacent systems. Computed once and shared with the Dimension agents that need it.
+- **Adjacent System:** a system the spec depends on that lives outside the current repo (for example a .NET service or the CMS), declared by the Reviewer at intake.
+- **Traversal:** the page-graph expansion from pasted seeds through child pages and in-body links, gated by a budget confirmation before a large fetch.
+- **Report:** the timestamped markdown artifact written under `.spec-review/` (gitignored) for every Review, grouped by Hat.
+- **Approval Loop:** the interactive selection-and-post flow, enabled only by `--post`. Cancellable at every step, including a final "post none" exit.
+- **Attribution Footer:** the visible provenance line on every comment the command posts, so any later Review (by anyone) can recognise prior Findings.
+- **Near-duplicate:** an existing comment (a prior run's, a colleague's, or a human's) that resembles a candidate Finding closely enough to flag for a human tiebreak in the Approval Loop.
+
+See [`CLAUDE.md`](CLAUDE.md) / [`AGENTS.md`](AGENTS.md) for the locked design and [`docs/issues/unic-spec-review/PRD.md`](docs/issues/unic-spec-review/PRD.md) for the full specification.