Spectre Manifest

`@phcdevworks/spectre-manifest` is the manifest schema and contract tooling package of the Spectre system. It records package roles, layers, ownership boundaries, dependency rules, and AI/tooling guidance in one machine-readable source of truth, and validates each package's `spectre.manifest.json` a

This page is generated from the source repository’s README and ROADMAP on every build. Edit the source repository, not this file.

README

@phcdevworks/spectre-manifest

@phcdevworks/spectre-manifest is the manifest schema and contract tooling package of the Spectre system. It records package roles, layers, ownership boundaries, dependency rules, and AI/tooling guidance in one machine-readable source of truth, and validates each package’s spectre.manifest.json against it.

Maintained by PHCDevworks. It is consumed as a check:ecosystem devDependency by every other package in the Spectre ecosystem, including packages in project-design, to validate their spectre.manifest.json declarations as part of npm run check.

Repository Snapshot

Field Value
Project team project-shell
Repository role Spectre M (cross-cutting) manifest schema and contract tooling
Package/artifact @phcdevworks/spectre-manifest
Current version/status 1.1.0

Standard Workflow

  1. Read AGENTS.md, then the agent-specific guide for the task.
  2. Check TODO.md and ROADMAP.md for current scope.
  3. Make the smallest repo-local change that satisfies the task.
  4. Run corepack pnpm verify when validation is required or practical.
  5. Update docs and CHANGELOG.md only when behavior, public contracts, or release-relevant metadata changed.

Documentation Map

Guide Path
Agent rules AGENTS.md
Claude Code CLAUDE.md
Codex CODEX.md
Copilot COPILOT.md
Jules JULES.md
Roadmap ROADMAP.md
Todo TODO.md
Changelog CHANGELOG.md
Security SECURITY.md

npm version CI License Node

Workspace for the Spectre manifest package and ecosystem contract. The manifest records package roles, layers, ownership boundaries, dependency rules, and AI/tooling guidance in one machine-readable source of truth.

Contributing | Changelog | Roadmap | Security Policy

Source of truth

spectre.manifest.json (root) and packages/spectre-manifest/schema/spectre.manifest.schema.json are the source of truth for the Spectre architecture contract. Everything else is derived from or validated against them.

Layer Path Rule
Manifest data spectre.manifest.json Records package roles, layers, dependencies, and AI guidance
Contract authority packages/spectre-manifest/schema/spectre.manifest.schema.json JSON Schema (draft 2020-12) — structural contract authority
Public types packages/spectre-manifest/src/types.ts TypeScript contract surface — must mirror the schema
Generated dist packages/spectre-manifest/dist/ Never edit directly — regenerated by pnpm build

After any schema, type, or manifest change: run pnpm build then pnpm validate:manifest (or corepack pnpm verify / npm run check) to confirm the contract is internally consistent.

When to use this package

  • You need a machine-readable contract describing Spectre package roles, layer membership, and dependency rules.
  • You are writing tooling, CI scripts, AI agent docs, or scaffolding that needs to understand the Spectre ecosystem structure programmatically.
  • You want to validate a spectre.manifest.json file against the published schema.

When not to use this package

  • You need runtime reactive state, routing, styling, or component logic — those belong in other Spectre packages.
  • You need a generic JSON schema library — this package is purpose-built for Spectre architecture contracts only.

Capabilities

  • Defines the official Spectre package and layer map.
  • Requires a root schemaVersion so tools know which manifest contract they validated.
  • Models allowed and forbidden dependency relationships.
  • Publishes a JSON schema and TypeScript validation utilities.
  • Validates schema rules plus semantic concerns such as duplicate layer order and dependency cycles.
  • Gives humans, CI, scaffolding, docs, and AI workflows the same architecture contract.

Install

npm install @phcdevworks/spectre-manifest

Quick Start

Validate a manifest object:

import { validateManifest } from '@phcdevworks/spectre-manifest'
import manifest from './spectre.manifest.json' with { type: 'json' }

const result = validateManifest(manifest)

if (!result.valid) {
  console.error(result.issues)
}

Validate a manifest file:

import { formatManifestValidationIssues, validateManifestFile } from '@phcdevworks/spectre-manifest'

const result = await validateManifestFile('spectre.manifest.json')

if (!result.valid) {
  console.error(formatManifestValidationIssues(result.issues))
}

Use the validate CLI:

npx spectre-manifest-validate spectre.manifest.json
npx spectre-manifest-validate spectre.manifest.json --json

Check a downstream package against its manifest entry:

npx spectre-manifest-check spectre.manifest.json ./path/to/your-package
npx spectre-manifest-check spectre.manifest.json ./path/to/your-package --json

spectre-manifest-check reads the package’s package.json, confirms it is registered in the manifest, verifies that all declared Spectre dependencies are present, and flags any undeclared ones. Exit code 0 means compliant; exit code 1 means issues were found or the package is not registered.

Import the published manifest document directly (no need to fetch or check out this repo):

import manifest from '@phcdevworks/spectre-manifest/manifest' with { type: 'json' }

API

Runtime exports:

  • validateManifest
  • validateManifestFile
  • formatManifestValidationIssues
  • loadManifestSchema
  • manifestSchemaPath
  • checkPackageAgainstManifest
  • formatPackageCheckIssues

Published schema export:

  • @phcdevworks/spectre-manifest/schema

Published manifest export:

  • @phcdevworks/spectre-manifest/manifest — ships spectre.manifest.json itself (the living architecture contract, versioned and pinned alongside the schema and validation tooling)

Type exports include SpectreManifest, SpectrePackageDefinition, SpectreLayerDefinition, ManifestRules, ManifestAiGuidance, PackageCheckResult, and PackageCheckIssue.

Boundaries

This package owns architecture metadata, schema, and validation. It does not own rendering, styling, routing, reactive state, component implementation, or framework adapters.

Development

corepack pnpm install
pnpm verify

Useful scripts:

  • pnpm build builds the package.
  • pnpm typecheck validates TypeScript without emitting files.
  • pnpm test builds and runs the Node test suite.
  • pnpm validate:manifest validates spectre.manifest.json.
  • pnpm verify runs the standard workspace verification flow.

AI-agent coordination starts in AGENTS.md, with companion guidance in CLAUDE.md, CODEX.md, COPILOT.md, JULES.md, and .github/copilot-instructions.md.

Troubleshooting

Problem Likely cause Fix
pnpm verify fails with TTY error Running in non-interactive shell without CI=true Prefix with CI=true pnpm verify
validate:manifest reports unknown layer spectre.manifest.json references a layer not defined in schema Add the layer to the manifest or fix the reference
Type errors after schema change TypeScript types and schema are out of sync Update packages/spectre-manifest/src/types.ts to match schema changes
Tests fail after schema change Tests import from dist/ which is stale Run pnpm build before pnpm test

AI and automation boundaries

Claude Code (claude-sonnet-4-6) is the primary development agent for this repository. Codex handles release readiness and production stabilization. Jules handles small, bounded automated maintenance. GitHub Copilot provides development support.

Claude Code does not create git commits. All Claude Code changes are prepared and validated, then handed off to Bradley Potts for human review and commit. Jules commits bounded automated maintenance tasks autonomously when all validation gates pass.

Protected from automated change: packages/spectre-manifest/schema/spectre.manifest.schema.json, packages/spectre-manifest/src/types.ts, packages/spectre-manifest/src/index.ts, schemaVersion values, and packages/spectre-manifest/dist/. See AGENTS.md for full agent governance and boundary rules.

Contributing

See CONTRIBUTING.md. The gate is CI=true corepack pnpm verify. Schema and validation behavior are public contract surface — breaking changes require a schemaVersion rationale. See AGENTS.md for boundaries.

Release Notes

See CHANGELOG.md.

License

MIT. See LICENSE.

Roadmap

Spectre Manifest Roadmap

spectre-manifest is the infrastructure layer that defines the machine-readable contract system for the Spectre ecosystem. It owns schema definitions, manifest validation tooling, and the contract authority that downstream packages reference to prove they are correctly wired into the Spectre system.

Its job is to make contracts enforceable, not to define UI behavior or package logic.

1. Current Repo Assessment

Strengths

  • spectre.manifest.json is in place as the root machine-readable contract anchor with schemaVersion: "0.1".
  • Full JSON Schema (draft 2020-12) with AJV validation covering structural and semantic rules.
  • TypeScript types, validator, checker, and CLIs (spectre-manifest-validate, spectre-manifest-check) published as @phcdevworks/spectre-manifest.
  • Passing test suite covering manifest validation (happy path, parse errors, schema errors, semantic checks) and downstream package compliance checks.
  • CI pipeline on GitHub Actions running pnpm verify across Node 22 and 24.
  • CHANGELOG.md documents contract releases in Keep a Changelog format.
  • All core Spectre packages registered, including @phcdevworks/spectre-base (the renamed spectre-wordpress-themes).
  • spectre-manifest-diff CLI classifies manifest changes as additive, semantic, or breaking.
  • spectre.manifest.json is published via a ./manifest export alongside the existing ./schema export.

Remaining gaps

None. All phases are complete; future work is demand-driven only.

2. Roadmap

P0: Contract Authority / Must-Do

P0.1 Manifest Schema Versioning ✓ Complete

schemaVersion: "0.1" is declared in both spectre.manifest.json and the JSON Schema. Validation fails on missing or unrecognized versions.

P0.2 Full Package Coverage in the Manifest ✓ Complete

All active Spectre packages are registered. spectre-wordpress-themes was renamed to @phcdevworks/spectre-base (https://github.com/phcdevworks/spectre-base) and is registered with role wordpress-theme-foundation.

P0.3 CI Pipeline ✓ Complete

GitHub Actions workflow at .github/workflows/ci.yml runs pnpm verify (build, typecheck, test, validate:manifest) on every push and pull request against Node 22 and 24. Add a CI badge to README.md when the repository is public.

P0.4 Downstream Consumer Validation Tooling ✓ Complete

The spectre-manifest-check CLI (backed by checkPackageAgainstManifest in src/checker.ts) lets a downstream package validate its package.json against its manifest entry — checking registration, declared exports, and Spectre dependency declarations. The validation flow is documented in README.md and CONTRIBUTING.md, and @phcdevworks/spectre-init wires it into its check:ecosystem script alongside spectre-manifest-validate.

P1: Maintainer and Consumer Clarity

P1.1 Document Manifest Structure for Contributors ✓ Complete

Manifest entry structure, a template entry, and validation instructions are documented in README.md and CONTRIBUTING.md.

P1.2 Manifest Changelog ✓ Complete

CHANGELOG.md is in place in Keep a Changelog format, documenting contract additions, updates, and deprecations starting with the 1.0.0 release.

P2: Controlled Improvement — Complete

P2.1 Automated Package Contract Diffing ✓ Complete

spectre-manifest-diff CLI (packages/spectre-manifest/src/diff-cli.ts, differ.ts) compares two manifest files and classifies every change as additive, semantic, or breaking. Exits non-zero on breaking changes. diffManifests / formatManifestDiff exported from the public API for programmatic use. Covered by test/differ.test.mjs.

P2.2 Public Manifest Registry Evaluation ✓ Complete

Decision recorded in DECISION-manifest-distribution.md: ship spectre.manifest.json from the existing @phcdevworks/spectre-manifest package via a new ./manifest export (mirrors ./schema). Keeps schema and manifest versioned together and pinnable through the existing npm dependency. Follow-up implemented: the ./manifest export is live, spectre.manifest.json is copied into the package during pnpm build and shipped in the npm tarball via files, and usage is documented in README.md.

3. Explicitly Out of Scope

  • Do not define UI behavior or component structure here
  • Do not add package-specific logic here — this is schema and validation infrastructure only
  • Do not absorb token generation or CSS output into this repository
  1. Schema versioning ✓
  2. Full package coverage ✓
  3. CI pipeline ✓
  4. Downstream consumer validation tooling ✓
  5. Document manifest structure for contributors ✓
  6. Manifest changelog ✓
  7. Contract diffing tooling ✓ (spectre-manifest-diff CLI)
  8. Evaluate public registry ✓ (decision: ./manifest export from existing package)

All phases complete. No active roadmap items. Future work is demand-driven only.