@phcdevworks/spectre-manifest

@phcdevworks/spectre-manifest defines the application and module metadata contracts of the Spectre platform. It gives Spectre tooling a consistent way to describe, validate, and integrate applications and their capabilities.

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	2.0.0

How It Works Day to Day

There are two kinds of manifest file:

• Central manifest — spectre.manifest.json in this repo. It lists every Spectre package, its layer, its public exports, and which Spectre packages it may depend on. It ships to npm as @phcdevworks/spectre-manifest/manifest.
• Satellite manifests — each Spectre repo (spectre-ui, spectre-shell, and so on) keeps its own copy of spectre.manifest.json. That repo's npm run check runs spectre-manifest-check against it, so the repo fails its own gate if its package.json drifts from its manifest entry.

The satellites are checked automatically; the central manifest is not. When a package adds or removes exports or Spectre dependencies, its satellite gets updated in that repo and the central copy here falls behind. To catch that:

npm run reconcile   # compares central entries with each repo's satellite on GitHub main

✓ means in sync. △ lists the field that differs (central is this repo, satellite is the package repo). Copy the satellite value into spectre.manifest.json, run npm run check, and record the change under [Unreleased] in CHANGELOG.md. Run reconcile after any batch of package releases across the ecosystem and before releasing this package.

Use It In Your Project So AI Knows Spectre

Any app or website that uses Spectre packages can install the manifest so AI agents know what each package does, what it exports, and what the dependency rules are.

1. Install it as a dev dependency:

   npm install -D @phcdevworks/spectre-manifest

2. Point your agents at it. Add this to the project's CLAUDE.md or AGENTS.md:

   ## Spectre Packages
   Before choosing, importing, or adding any @phcdevworks package, read
   node_modules/@phcdevworks/spectre-manifest/spectre.manifest.json —
   use its `packages` (what each does, its exports), `rules`, and `ai`
   sections. Import only the exports listed there.

Installing alone does nothing; step 2 is what makes agents read it. Do not add spectre-manifest-check to an app's gate — that check is for registered Spectre packages, and an app is not registered in the manifest.

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
Grok	GROK.md
Roadmap	ROADMAP.md
Todo	TODO.md
Changelog	CHANGELOG.md
Security	SECURITY.md

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.

Installation

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.

It returns structured issues for malformed package metadata and checks declared exports when an exports field is present, including root shorthand and conditional targets. Null targets do not satisfy declared exports, and a blocking default cannot be bypassed by a later condition. See the package usage documentation for details.

spectre-manifest-diff treats an absent or empty allowedTargets list as unrestricted: introducing a non-empty list is breaking, and clearing it is additive. Breaking diffs exit with code 1.

For consumers, only an absent list is unrestricted; [] permits no consumers. Introducing a consumer list or removing a listed consumer is breaking. Removing the restriction entirely or adding to an existing list is additive.

Diffs also report metadata changes as semantic, including package-manager and repository fields, notes, and rule reasons. Package and layer names such as constructor are handled as ordinary registry entries.

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 package source and root TypeScript scripts without emitting files.
• pnpm test builds and runs the Node test suite.
• pnpm validate:manifest validates spectre.manifest.json.
• pnpm test:package builds and packs the package, installs the tarball into a temporary consumer, and checks public imports, declarations, bundled data, and all three installed CLIs.
• pnpm verify runs the standard workspace verification flow, including README version parity and test:package.

Development uses the pinned pnpm 12.11.2 version and Node 26 type definitions across the workspace. Supported runtime versions are unchanged. CI runs on Node 22.13.0 (the supported minimum), current Node 22, Node 24, and Node 26. The Node 24 job also runs pnpm audit --audit-level high to catch known high and critical dependency advisories; this check requires registry access. The packed-install check needs registry access for runtime dependencies, disables install scripts, and removes its temporary consumer on completion or failure.

AI-agent coordination starts in AGENTS.md, with companion guidance in CLAUDE.md, CODEX.md, COPILOT.md, JULES.md, GROK.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 releases, including cutting tagged releases and GitHub Releases, and production stabilization. Jules handles small, bounded automated maintenance. GitHub Copilot provides development support.

Claude Code has no git access; it validates its work and hands off to Codex (or Bradley Potts) to commit. Codex, Copilot, and Jules have commit, push, and tag authority; Grok has commit and push authority only. Only Codex cuts releases, and only when Bradley Potts asks. Publishing to npm remains Bradley Potts's sole authority. See AGENTS.md for the full commit-policy and release-authority grant.

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.