skills.rest
arittr
arittrCOMMUNITY
Explore all skills by this author →
GitHub

versioning-constitutions

Create versioned constitution directories to snapshot architectural rules.

19|Updated Oct 21, 2025
Search Tags:#architecture#versioning#documentation#tech stack#patterns#constitution#governance
One-click install
npx skills add https://github.com/arittr/spectacular --skill versioning-constitutions
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: versioning-constitutions
Source: https://github.com/arittr/spectacular/tree/main/skills/versioning-constitutions
Command: npx skills add https://github.com/arittr/spectacular --skill versioning-constitutions

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill addresses the challenge of managing evolving architectural rules, tech stack changes, and foundational patterns without losing historical context or breaking existing references. It ensures that changes to core project governance are explicit, auditable, and easily reversible.

Core Features & Use Cases

  • Immutable Versioning: Creates new, immutable snapshots of architectural rules (constitutions) whenever foundational patterns or tech stack elements change, preserving a clear history.
  • Automated Migration: Handles the creation of new version directories, copying existing content, and updating symlinks to ensure seamless transitions between versions.
  • Change Documentation: Mandates thorough documentation of all changes in meta.md, including the "what" and "why," to maintain context for future reference.
  • Use Case: When your team decides to adopt a new error handling library or deprecate an old pattern, use this Skill to create a new constitution version, update the relevant files, and automatically document the change, ensuring all developers are aware and historical context is maintained.

Quick Start

Check current version

cat docs/constitutions/current/meta.md

Create new version (e.g., v2)

mkdir -p docs/constitutions/v2 cp docs/constitutions/current/*.md docs/constitutions/v2/

Update symlink

rm docs/constitutions/current ln -s v2 docs/constitutions/current

Frequently Asked Questions about versioning-constitutions

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I version architectural rules when tech stack or patterns change?▼

Versioning constitutions captures immutable snapshots of your architecture when foundational changes occur. Create a new version directory (e.g., v2), copy current constitution files into it, update the symlink to point to the new version, and document changes in meta.md. This preserves history, enables rollback, and keeps all architectural decisions auditable.

When should I create a new constitution version?▼

Create a new constitution version when your team adopts new patterns, deprecates old ones, changes tech stack elements, or modifies architectural boundaries. Versioning is needed whenever foundational rules evolve significantly enough that developers need clear before-and-after documentation and the ability to reference prior decisions.

How do I ensure all cross-references update when I version my architecture?▼

After copying constitution files into a new version directory and updating the current symlink, verify cross-references between architecture.md, patterns.md, tech-stack.md, schema-rules.md, and testing.md. Document the rationale and changelog in meta.md so developers understand what changed and why, keeping all internal links consistent.

Can I rollback architectural changes if a new constitution version doesn't work?▼

Yes. Immutable versioning preserves all prior constitution versions, letting you revert the current symlink to an earlier version if needed. Each snapshot remains intact with full historical context, so you can safely experiment with architectural changes knowing you can revert to a known-good state.

What documentation should I include when versioning architecture?▼

When creating a new constitution version, document the rationale and changelog in meta.md explaining what changed, why it changed, and how it affects developers. Include the "what" and "why" for each modification to patterns.md, tech-stack.md, schema-rules.md, and testing.md so future team members understand the decision context.

Do I need to manually copy files when creating a new architecture version?▼

The versioning process includes copying existing constitution files into the new version directory to create an immutable snapshot. After copying, update meta.md and relevant constitution files to reflect changes, then update the current symlink. This workflow ensures seamless transitions while preserving the complete historical record.

Related Skills

Explore More Software Engineering Skills→
ArvorCoArvorCo
96

constitution

Create or update a project constitution defining coding principles and governance rules.

Community
Advanced
lionbenjaminlionbenjamin
15

constitute

Document non-negotiable technical constraints and governance for project scoping.

Community
Advanced
kenmulfordkenmulford

decision-log

Log project decisions into a structured .xlsx decision log with specified fields.

Community
Advanced
Community-ChestsCommunity-Chests

agreement-versioning

Track immutable governance agreement versions with semver-based snapshots and diffs.

Official
Advanced