docs: update CLAUDE.md and README for spec-tree plugin and CI/CD

simonheimlicher · simonheimlicher · commit a54aa2f1b45b · 2026-03-18T02:12:11.000+01:00
- Deprecate spx spec/spx spx CLI domains in favor of spec-tree plugin
- Replace spx:understanding-spx/managing-spx skill refs with spec-tree:* skills
- Document CI/CD pipeline (OIDC Trusted Publishing, Sigstore provenance)
- Add publishing instructions to README
- Update architecture tree to reflect current src/ layout
- Bump to 0.1.6
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -6,57 +6,41 @@
 
 ---
 
-## 🚨 MIGRATION IN PROGRESS: specs/ → spx/
+## Spec Management
 
-**We are migrating from the legacy `specs/` framework to the CODE Framework in `spx/`.**
+### Deprecated: `spx spec` and `spx spx` commands
 
-| Directory | System         | Status                                                  |
-| --------- | -------------- | ------------------------------------------------------- |
-| `spx/`    | CODE Framework | **Primary** - use for all new work                      |
-| `specs/`  | Legacy         | **Frozen** - do not modify unless explicitly instructed |
+The `spec` and `spx` CLI domains are **deprecated** and will be removed. They are replaced by the **spec-tree** plugin, which provides the same functionality as Claude Code skills.
 
-**Key differences:**
+### Current: spec-tree plugin (skill-only)
 
-| Aspect          | Legacy (`specs/`)                | CODE Framework (`spx/`)       |
-| --------------- | -------------------------------- | ----------------------------- |
-| Test location   | Graduate to global `tests/`      | Stay in container `tests/`    |
-| Status tracking | `DONE.md` in container           | `outcomes.yaml` ledger        |
-| Philosophy      | Task-driven (backlog/doing/done) | Outcome-driven, durable specs |
+The **spec-tree** plugin (`outcomeeng/claude/plugins/spec-tree`) is the active system for managing specification trees. It provides seven skills:
 
-**Migration tracking:** Each migrated container has an `SPX-MIGRATION.md` file documenting reverse-graduation of tests.
+| Skill                        | Purpose                                                        |
+| ---------------------------- | -------------------------------------------------------------- |
+| `/spec-tree:understanding`   | Load methodology foundation (node types, ordering, assertions) |
+| `/spec-tree:contextualizing` | Load context for a specific work item (walks tree to target)   |
+| `/spec-tree:authoring`       | Create specs, ADRs, PDRs, enablers, outcomes                   |
+| `/spec-tree:decomposing`     | Break nodes into children with proper ordering                 |
+| `/spec-tree:testing`         | Manage spec-test lock file lifecycle                           |
+| `/spec-tree:refactoring`     | Restructure the spec tree (move, consolidate, extract)         |
+| `/spec-tree:aligning`        | Review for gaps, contradictions, and consistency               |
 
-**Primary guide for new work:** [`spx/CLAUDE.md`](spx/CLAUDE.md)
+### Legacy: `specs/` directory
+
+The `specs/` directory uses the legacy task-driven system (backlog/doing/done with `DONE.md`). It is **frozen** — do not modify unless explicitly instructed.
 
 ---
 
 ## BSP Numbers
 
 - BSP stands for Binary Space Partitioning.
-- BSP numbers are only sibling-unique. Always use the complete path `capability-NN/feature-NN/story-NN` and `capability-NN/feature-NN/adr-NN` etc. when interacting with the user, creating handoff documents or otherwise referring to artifcats within the `specs/` and `spx/` directories.
-
----
-
-### Finding Work
-
-**Rule**: Lower BSP number = higher priority. Complete `21-*.feature` before `32-*.feature`.
-
-> **Note:** The `spx spec` and `spx spx` domain commands are not yet implemented. Use skills or manual inspection to find work items.
-
-```bash
-# These commands do NOT work yet:
-# spx spec status
-# spx spec next
-
-# Instead, use skills:
-/spx:understanding-spx   # Load context for a work item
-/spx:managing-spx        # Find next work item, create specs
-```
-
-Full CODE Framework rules: [`spx/CLAUDE.md`](spx/CLAUDE.md)
+- BSP numbers are only sibling-unique. Always use the complete path `capability-NN/feature-NN/story-NN` and `capability-NN/feature-NN/adr-NN` etc. when interacting with the user, creating handoff documents or otherwise referring to artifacts within the `specs/` and `spx/` directories.
+- Lower BSP number = higher priority. Complete `21-*.feature` before `32-*.feature`.
 
 ---
 
-## 🚨 VALIDATION GATE (MANDATORY BEFORE COMMIT)
+## Validation Gate (Mandatory Before Commit)
 
 **NEVER commit without passing validation.** This is *non-negotiable*.
 
@@ -111,26 +95,6 @@ All validation runs through `spx validation` subcommands. Use pnpm scripts or ca
 
 ---
 
-## Finding Work Items
-
-> **Note:** The `spx spec` and `spx spx` domain commands are not yet implemented.
-
-**For now, use skills to find and understand work:**
-
-```bash
-/spx:managing-spx        # Ask "what's next?" - finds next work item by hierarchy (capability -> feature -> story) and then by BSP order
-/spx:understanding-spx   # Load full context for a specific work item
-```
-
-**Or inspect the `spx/` directory manually:**
-
-- Lower BSP number = higher priority
-- Check `outcomes.yaml` for status (missing = unknown, has entries = check if tests pass)
-
-**For CODE Framework details**: Read [`spx/CLAUDE.md`](spx/CLAUDE.md)
-
----
-
 ## Session Management
 
 Use `spx session` to manage work handoffs between agent contexts.
@@ -220,10 +184,11 @@ Commands output XML-style tags for easy parsing by automation tools:
 
 ## Technical Stack
 
-- **Language**: TypeScript
-- **Build**: tsup
+- **Language**: TypeScript (ESM)
+- **Build**: tsup (esbuild-based)
 - **Testing**: Vitest
 - **CLI**: Commander.js
+- **CI/CD**: GitHub Actions with OIDC Trusted Publishing and Sigstore provenance
 
 ## Development
 
@@ -236,8 +201,15 @@ Use `pnpm run` scripts (e.g. `pnpm run validate`, `pnpm test`) for development 
 ```
 src/
 ├── commands/      # CLI command implementations
-│   ├── validation/  # spx validation subcommands
-│   └── session/     # spx session subcommands
+│   ├── claude/      # spx claude subcommands (deprecated)
+│   ├── session/     # spx session subcommands
+│   ├── spec/        # spx spec subcommands (deprecated)
+│   └── validation/  # spx validation subcommands
+├── domains/       # Domain routers
+│   ├── claude/      # (deprecated)
+│   ├── session/
+│   ├── spec/        # (deprecated)
+│   └── validation/
 ├── validation/    # Lint, typecheck, circular dep logic
 ├── session/       # Session lifecycle and storage
 ├── config/        # Configuration loading
@@ -246,25 +218,6 @@ src/
 ├── status/        # Status state machine
 ├── reporter/      # Output formatting
 ├── tree/          # Hierarchical tree building
+├── precommit/     # Pre-commit hook orchestration
 └── lib/           # Shared utilities
 ```
-
-### Status Determination
-
-**CODE Framework (`spx/`)** - status via `outcomes.yaml` ledger:
-
-| State     | Condition                          | Required Action                 |
-| --------- | ---------------------------------- | ------------------------------- |
-| Unknown   | Test Files links don't resolve     | Write tests                     |
-| Pending   | Tests exist, not all passing       | Fix code or fix tests           |
-| Stale     | Spec or test blob changed          | Re-commit with `spx spx commit` |
-| Passing   | All tests pass, blobs unchanged    | None—potential realized         |
-| Regressed | Was passing, now fails, blobs same | Investigate and fix             |
-
-**Legacy (`specs/`)** - status via `tests/` directory:
-
-| State       | Condition                           |
-| ----------- | ----------------------------------- |
-| OPEN        | Missing or empty `tests/` directory |
-| IN PROGRESS | `tests/` has files but no `DONE.md` |
-| DONE        | `tests/DONE.md` exists              |
diff --git a/README.md b/README.md
@@ -11,13 +11,14 @@ Developer CLI for code validation and session management.
 - **Unified validation**: Run ESLint, TypeScript, and circular dependency checks through a single command
 - **Session management**: Queue, claim, and hand off work between agents
 - **Multiple formats**: Text, JSON output for CI and automation
+- **Secure publishing**: OIDC Trusted Publishing with Sigstore provenance via GitHub Actions
 
 All commands are domain-scoped (e.g., `spx validation`, `spx session`) and support `--quiet` and `--json` flags for CI and automation.
 
 ## Installation
 
 ```bash
-pnpm add -g @outcomeeng/spx
+npm install -g @outcomeeng/spx
 ```
 
 ### From Source
@@ -62,20 +63,12 @@ priority: high
 ---
 # Implement feature X
 EOF
-# Output:
-# Created handoff session <HANDOFF_ID>2026-01-15_08-30-00</HANDOFF_ID>
-# <SESSION_FILE>/path/to/.spx/sessions/todo/2026-01-15_08-30-00.md</SESSION_FILE>
-
-# Or create empty session and edit the file directly
-spx session handoff
-# Then edit the <SESSION_FILE> path returned
 
 # List all sessions
 spx session list
 
 # Claim the highest priority session
 spx session pickup --auto
-# Output: Claimed session <PICKUP_ID>2026-01-15_08-30-00</PICKUP_ID>
 
 # Release session back to queue
 spx session release
@@ -87,10 +80,14 @@ spx session show <session-id>
 spx session delete <session-id>
 ```
 
-Sessions are stored in `.spx/sessions/` with priority-based ordering (high → medium → low) and FIFO within the same priority. Commands output parseable `<PICKUP_ID>`, `<HANDOFF_ID>`, and `<SESSION_FILE>` tags for automation.
+Sessions are stored in `.spx/sessions/` with priority-based ordering (high > medium > low) and FIFO within the same priority. Commands output parseable `<PICKUP_ID>`, `<HANDOFF_ID>`, and `<SESSION_FILE>` tags for automation.
 
 See [Session Recipes](docs/how-to/session/common-tasks.md) for detailed usage patterns.
 
+### Spec Management (deprecated)
+
+The `spx spec` and `spx spx` CLI domains are **deprecated**. Spec tree management has moved to the **spec-tree** Claude Code plugin, available at [`outcomeeng/claude/plugins/spec-tree`](https://github.com/simonheimlicher/spx-claude). The plugin provides skills for understanding, authoring, decomposing, contextualizing, testing, refactoring, and aligning specification trees.
+
 ## Development
 
 ### Setup
@@ -128,21 +125,39 @@ pnpm run knip           # Unused code detection
 
 The `pnpm run` scripts use `node bin/spx.js` internally, so they work without a global link. Once linked, you can also use `spx validation all` etc. directly.
 
+## CI/CD
+
+The project uses GitHub Actions for continuous integration and publishing:
+
+- **CI** (`ci.yml`) — Runs validate, test, and build on Node 22 and 24 for every push to `main` and every pull request. Includes dependency review to block PRs introducing vulnerable dependencies.
+- **Publish** (`publish.yml`) — Triggered by `v*` tags. Uses OIDC Trusted Publishing (no stored npm tokens) with Sigstore provenance attestation. Requires manual approval via the `npm-publish` GitHub Environment.
+- **Scorecard** (`scorecard.yml`) — Weekly OpenSSF Scorecard assessment, results published to the GitHub Security tab.
+
+### Publishing a Release
+
+1. Bump the version in `package.json`
+2. Commit and tag: `git tag vX.Y.Z`
+3. Push: `git push origin main && git push origin vX.Y.Z`
+4. Approve the deployment in the GitHub Actions `npm-publish` environment
+5. The package is published with provenance — verify with `npm audit signatures`
+
 ## Technical Stack
 
-- **TypeScript** - Type-safe implementation
-- **Commander.js** - CLI framework
-- **Vitest** - Testing framework
-- **tsup** - Build tool
-- **ESLint 9** - Linting with flat config
+- **TypeScript** — Type-safe implementation (ESM)
+- **Commander.js** — CLI framework
+- **Vitest** — Testing framework
+- **tsup** — Build tool (esbuild-based)
+- **ESLint 9** — Linting with flat config
+- **GitHub Actions** — CI/CD with OIDC Trusted Publishing
 
 ## Architecture
 
 ```
 src/
 ├── commands/      # CLI command implementations
-│   ├── validation/  # spx validation subcommands
-│   └── session/     # spx session subcommands
+│   ├── session/     # spx session subcommands
+│   └── validation/  # spx validation subcommands
+├── domains/       # Domain routers
 ├── validation/    # Lint, typecheck, circular dep logic
 ├── session/       # Session lifecycle and storage
 ├── config/        # Configuration loading
@@ -151,6 +166,7 @@ src/
 ├── status/        # Status state machine
 ├── reporter/      # Output formatting
 ├── tree/          # Hierarchical tree building
+├── precommit/     # Pre-commit hook orchestration
 └── lib/           # Shared utilities
 ```
 
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@outcomeeng/spx",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Developer CLI for code validation and session management",
   "type": "module",
   "bin": {
diff --git a/spx/CLAUDE.md b/spx/CLAUDE.md
@@ -1,33 +1,20 @@
-# spx/ Directory Guide (CODE Framework)
+# spx/ Directory Guide (Spec Tree)
 
-This guide explains WHEN to invoke spx skills. It is a **router** that tells you which skill to use. The skills themselves contain the HOW (detailed procedures, templates, structure definitions).
+This guide explains the `spx/` directory structure and how to work with specification trees.
 
----
-
-## 🚨 DISAMBIGUATION: spx/ vs specs/
-
-**Before proceeding, determine which system this project uses:**
-
-| Directory | System         | Skills to Use                                       |
-| --------- | -------------- | --------------------------------------------------- |
-| `spx/`    | CODE framework | `spx:understanding-spx`, `spx:managing-spx`         |
-| `specs/`  | Legacy         | `specs:understanding-specs`, `specs:managing-specs` |
-
-**If BOTH directories exist**: Ask the user which system they want to work with.
+Spec tree management is handled by the **spec-tree** Claude Code plugin (`outcomeeng/claude/plugins/spec-tree`). Use its skills for all spec operations:
 
-**If `specs/` exists**: Read `specs/CLAUDE.md` for legacy system guidance.
+| Skill                        | Purpose                                                        |
+| ---------------------------- | -------------------------------------------------------------- |
+| `/spec-tree:understanding`   | Load methodology foundation (node types, ordering, assertions) |
+| `/spec-tree:contextualizing` | Load context for a specific work item                          |
+| `/spec-tree:authoring`       | Create specs, ADRs, PDRs, enablers, outcomes                   |
+| `/spec-tree:decomposing`     | Break nodes into children with proper ordering                 |
+| `/spec-tree:testing`         | Manage spec-test lock file lifecycle                           |
+| `/spec-tree:refactoring`     | Restructure the spec tree                                      |
+| `/spec-tree:aligning`        | Review for gaps, contradictions, and consistency               |
 
-**Fully qualified skill names** (required when both plugins are installed):
-
-```bash
-# CODE framework spx/ projects
-/spx:understanding-spx
-/spx:managing-spx
-
-# Legacy specs/ projects
-/specs:understanding-specs
-/specs:managing-specs
-```
+The `specs/` directory uses the legacy task-driven system and is **frozen**.
 
 ---
 
@@ -126,7 +113,7 @@ tests:
 
 ## When to Invoke Skills
 
-### Before Implementing ANY Work Item → `/spx:understanding-spx`
+### Before Implementing ANY Work Item → `/spec-tree:contextualizing`
 
 **BLOCKING REQUIREMENT**
 
@@ -136,30 +123,35 @@ tests:
 - User references a work item file
 - You're about to write implementation code
 
-**What it does**: Loads complete context hierarchy (PRD → ADRs → capability → feature → story).
+**What it does**: Walks the tree from product root to target node, collecting ancestor specs and context.
 
-### When Creating/Organizing Specs → `/spx:managing-spx`
+### When Creating/Organizing Specs → `/spec-tree:authoring`
 
 **BLOCKING REQUIREMENT**
 
 **Trigger conditions:**
 
 - User says "create a PRD", "add an ADR", "create capability/feature/story"
-- User asks "what's next to work on?"
-- You need templates or BSP numbering rules
+- You need templates or ordering rules
+
+**What it does**: Provides templates, sparse integer ordering, structure guidance.
+
+### When Asking "What's Next?" → `/spec-tree:contextualizing`
 
-**What it does**: Provides templates, BSP numbering, structure guidance.
+Use contextualizing to understand current state, then authoring or testing to act on it.
 
 ---
 
 ## Quick Reference: Skill Selection
 
-| User Says...         | Invoke                   | Do NOT                 |
-| -------------------- | ------------------------ | ---------------------- |
-| "Implement story-21" | `/spx:understanding-spx` | Read story.md directly |
-| "Create a PRD"       | `/spx:managing-spx`      | Search for templates   |
-| "What's next?"       | `/spx:managing-spx`      | Grep for work items    |
-| "Create a feature"   | `/spx:managing-spx`      | Calculate BSP yourself |
+| User Says...              | Invoke                       | Do NOT                 |
+| ------------------------- | ---------------------------- | ---------------------- |
+| "Implement story-21"      | `/spec-tree:contextualizing` | Read story.md directly |
+| "Create a PRD"            | `/spec-tree:authoring`       | Search for templates   |
+| "What's next?"            | `/spec-tree:contextualizing` | Grep for work items    |
+| "Create a feature"        | `/spec-tree:authoring`       | Calculate BSP yourself |
+| "Break this down"         | `/spec-tree:decomposing`     | Guess child structure  |
+| "Anything contradictory?" | `/spec-tree:aligning`        | Skim specs manually    |
 
 ---
 

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@outcomeeng/spx",`
`3`		`- "version": "0.1.5",`
	`3`	`+ "version": "0.1.6",`
`4`	`4`	`"description": "Developer CLI for code validation and session management",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"bin": {`