Spec-driven development: schema packages, bridges, guide API, CRUD CLI

[avrabe]

Context

Rivet's strategic positioning as a spec-driven SDLC engine. Schemas become distributable packages that define lifecycle methodologies, enforce compliance, teach AI agents, and produce audit evidence.

Spec: docs/superpowers/specs/2026-03-29-spec-driven-development-design.md (on docs/specs-and-plans branch)

Positioning

Schema as contract (enforces) + curriculum (teaches) + evidence (proves).

Phases

Phase 1: Schema package format + built-in packaging

• Add manifest.yaml to existing schemas (name, version, bridges, min_rivet_version)
• Add guidance fields to schema YAML (description, common-mistakes, example per type)
• rivet schema validate and rivet schema list
• Package existing schemas with docs and starters
• Built-in schema resolution (compiled via include_str!)

Phase 2: Bridge schemas + rivet init

• Bridge schema format (link_types + traceability_rules only, no artifact_types)
• BridgeFile struct, Schema::apply_bridges() loading mechanism
• Auto-resolution of bridges from manifests
• rivet init --schema aspice,stpa with bridge auto-detect + starter artifacts
• rivet schema new scaffolding

Phase 3: CLI enhancements

• rivet get command (single artifact read, --format json/yaml)
• --format json on validate, stats, matrix, stpa, coverage
• rivet modify --add-ref for source-ref management
• Note: rivet add/link/modify/remove already exist via mutate.rs/yaml_edit.rs

Phase 4: Guide API + CLI

• GuideReport struct in rivet-core (static schema guidance + dynamic project health)
• /api/v1/guide endpoint with sub-routes (depends on PR feat(api): oEmbed provider and Grafana JSON API endpoints #89)
• rivet guide CLI with all subcommands + --format json
• Uses cached diagnostics from AppState

Phase 5: Source refs

• source-refs field on Artifact struct (Vec<SourceRef>)
• Schema source-refs config (expect: optional/recommended/required, labels)
• Code comment cross-validation (// rivet: implements REQ-042)
• Dashboard + API integration

Phase 6: Git-based schema distribution

• Schema loading from git repos (extend existing externals sync)
• Version pinning in rivet.yaml (aspice@2.1.0)

Parallel execution

Phase 1 → (Phase 2 + Phase 3 + Phase 4 in parallel) → Phase 5 + Phase 6

Key codebase notes

• Existing CRUD: rivet add/link/modify/remove already work (mutate.rs, yaml_edit.rs)
• Schema format: list-of-structs, kebab-case keys (not map-style)
• baselines: config key already used for scoped validation — snapshot config uses snapshots: key
• rivet diff already exists for artifact directory comparison — snapshot diff uses rivet snapshot diff
• rivet init has existing --preset and --schema flags