@phcdevworks/spectre-manifest

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.0.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

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.

API

Runtime exports:

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

Published schema export:

• @phcdevworks/spectre-manifest/schema

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.