Forward-Only Design
This document describes Nexlem's forward-only stance — the architectural commitment
that schema, .nexlem/ layout, and agent prompt changes evolve forward without
preserved rollback paths. Consumers can use this document to understand what to
expect when upgrading the framework. Maintainers can use it as the policy bar —
no rollback code, no schema downgrade paths, and no re-export shims belong in PRs.
Scope: Forward-only design: no real users yet; no rollback story; focus on a solid base for future releases. This stance covers the current v2.x surface and is expected to hold for the foreseeable v2.x line.
What Forward-Only Means
Forward-only is not a single rule — it is a posture that shows up the same way across four cross-cutting areas of the framework. Each row below states the behavior once, in evergreen terms, and explains what it means for a consumer using Nexlem in their project.
| Area | Forward-only behavior | What it means for you |
|---|---|---|
| Schema migrations | Every nexlem-sdk invocation auto-runs pending migrations against the project's SQLite database. Migrations are lock-protected and fail fast on contention. No downgrade path ships; no rollback DDL is generated. | Always upgrade to the latest patch release. If a migration is wrong, the fix lands as a fix-forward patch and the auto-migrate runner applies it on the next invocation. |
.nexlem/ layout | Internal paths evolve as the framework matures. The auto-migrate runner handles the layout transition transparently on first invocation against an older project. No legacy-path shims or symlinks are preserved. | Don't depend on internal .nexlem/ paths from your own scripts. Use the documented nexlem-sdk query handlers — those are the public surface and follow the stability tiers in STABILITY.md. |
| Agent prompts | Agent prompts are .md Claude Code subagent files that ship with the framework. They are updated in place; the framework does not keep old prompt versions around for coexistence. | A new framework version ships new prompts. Re-running an in-flight campaign after an upgrade picks up the new prompts. If you need the old behavior, pin the framework version. |
| Removed features | When a feature is removed, it is removed — not deprecated with a long shim window. When the framework renames an internal module, it does not ship a re-export shim — consumers depend on the public skills/SDK surface, not internal modules. | Do not write automation against undocumented surfaces. Anything covered by STABILITY.md carries the stability promise of its tier; anything else may move without notice. |
No Rollback by Design
No rollback by design. Schema migrations apply forward only. If a migration is wrong, the fix lands as a fix-forward in the next patch release (e.g., v2.2.1) and the auto-migrate runner applies it on the next
nexlem-sdkinvocation. The framework does not ship downgrade SQL, and it does not preserve old.nexlem/layouts or old agent prompts for compatibility.
This is a deliberate trade. The cost of maintaining a rollback story — keeping every prior schema, layout, and prompt valid in parallel — would slow the framework's iteration speed without protecting any real consumer state today. The benefit is a single, current code path: one schema, one layout, one set of prompts at any moment, matching whatever framework version is installed globally.
If a migration leaves a project in a bad state, the recovery path is the next section — not a downgrade.
Removed Features
The following features are explicitly out of scope. They are not "deprecated and will be removed later" — they are not in the product and the framework does not plan to add them:
- Schema downgrade / rollback — forward-only by design; the fix-forward patch release is the supported path.
- Cleanup helper for legacy
node_modules/—/nexlem initdoes not createnode_modulesin your project, so there is no legacy directory for the framework to clean up. - yarn berry global support — yarn berry deprecated global installs; the supported package managers for installing Nexlem globally are bun, npm, pnpm, and yarn classic. See install.md for per-PM commands.
- Multi-version coexistence — one global framework version per machine. Future v2.x releases may revisit this if demand emerges.
- CMS or web admin UI for content management — Nexlem is Claude Code skill-based by design; a separate CMS surface is not on the roadmap.
- Telemetry / cost ledger — Nexlem runs on a Claude Code subscription, so the framework has no visibility into per-call cost and does not ship a cost-ledger surface.
Historical removal dates are in CHANGELOG.md.
Recovery Posture
If a migration leaves your project in an unworkable state:
- Restore from backup —
/nexlem backupsnapshots the project's SQLite database and config files; restoring rolls the project state back to a known-good point without rolling the framework version back. See COMMANDS.md for the backup and restore subcommands. - Re-initialize — for a project with no significant local state,
/nexlem initin a fresh directory is the fastest recovery path. The new project is created against the current framework version with the current schema and layout. - Seek support — open an issue at
github.com/nexlem/nexlem with the
nexlem-sdk infooutput attached. The doctor output captures the framework version, runtime checks, and the project's current state, which is what a triage starts from.
The recovery posture deliberately does not include a downgrade option. Downgrading the framework would not undo a forward-only schema or layout change, and offering it would muddy the design contract above.
Related Documents
- STABILITY.md — tier classifications and deprecation policy for Nexlem's public surfaces (SDK queries and skill commands). Forward-only design is the migration/layout policy; STABILITY.md is the public-surface contract. Each links to the other at its boundary.
- COMMANDS.md — full reference for
/nexlem backup,/nexlem init, and the other skill commands referenced in the recovery posture. - install.md — supported package managers and install verification, including the yarn berry note that pairs with the removed-features list above.
- CHANGELOG.md — per-release record of changes, including the historical dates of feature removals listed above.