@orchestrator-claude/definitions 3.5.0

package/kb/docs-constitution.md

@@ -0,0 +1,310 @@
+---
+title: "DOCS-CONSTITUTION - Documentation Governance Rules"
+category: "governance"
+tier: "critical"
+tags: ["documentation", "governance", "rules", "compliance"]
+template: "all"
+---
+
+# DOCS-CONSTITUTION - Documentation Governance Rules
+
+## Overview
+
+This document defines the rules and conventions for documentation governance in the **my-project** project. It serves as the source of truth for the Documentation Guardian system.
+
+**Project**: my-project
+**Template**: orchestrator
+**Constitution Preset**: orchestrator
+
+---
+
+## 1. Separation of Concerns
+
+### 1.1 project-guidelines/ (Technical Documentation)
+
+**Purpose**: Documentation for developers and LLM agents.
+
+**What belongs here:**
+- RFCs (Request for Comments)
+- ADRs (Architecture Decision Records)
+- Phase tracking files
+- Design documents
+- Technical specifications
+- Internal conventions
+
+**Structure:**
+```
+project-guidelines/
+  rfcs/
+    index.md
+    RFC-000-TEMPLATE.md
+    RFC-XXX-*.md
+  adrs/
+    index.md
+    ADR-XXX-*.md
+  README.md
+  MASTER-INDEX.md
+```
+
+### 1.2 docs/ (User Documentation)
+
+**Purpose**: Documentation for end users and external developers.
+
+**What belongs here:**
+- Getting started guides
+- Tutorials
+- API reference (public)
+- Configuration guides
+- Troubleshooting
+- Examples
+
+**Structure:**
+```
+docs/
+  README.md
+  getting-started.md
+  tutorials/
+  examples/
+  migration/
+  api/
+```
+
+### 1.3 Identification Patterns
+
+**Technical documents** (project-guidelines/):
+- Contains: RFC, ADR, TRACKING, PHASE, DESIGN, SPEC, PLAN
+- Filename patterns: `RFC-*.md`, `ADR-*.md`, `*-TRACKING.md`
+- Content patterns: workflow IDs, phase references, internal APIs
+
+**User documents** (docs/):
+- Contains: tutorial, guide, getting-started, example, how-to
+- Filename patterns: `*-guide.md`, `*-tutorial.md`
+- Content patterns: user-facing instructions, public API usage
+
+---
+
+## 2. Versioning Rules
+
+### 2.1 Semantic Versioning
+
+Follow SemVer 2.0.0:
+```
+MAJOR.MINOR.PATCH
+
+MAJOR: Breaking changes
+MINOR: New features (backwards compatible)
+PATCH: Bug fixes (backwards compatible)
+```
+
+### 2.2 Version Sources
+
+**Single Source of Truth**: `package.json`
+
+**Must Stay in Sync:**
+- package.json version
+- Latest git tag (v{version})
+- CHANGELOG.md header
+- RFC target versions (when applicable)
+
+### 2.3 Git Tags
+
+**Format**: `v{MAJOR}.{MINOR}.{PATCH}`
+
+**Examples:**
+- v1.0.0
+- v1.2.3
+- v2.0.0-beta.1
+
+**Rules:**
+- Create tag after package.json update
+- Never delete published tags
+- Use annotated tags for releases
+
+---
+
+## 3. Archival Rules
+
+### 3.1 When to Archive
+
+Archive documents when:
+- Not modified for 30+ days AND not protected
+- Associated phase/feature is complete
+- Explicitly marked as deprecated
+- Superseded by newer document
+
+### 3.2 Protected Documents (Never Archive)
+
+- RFCs (any status)
+- ADRs (any status)
+- CONSTITUTION.md
+- CLAUDE.md
+- README.md (any location)
+- Active tracking files
+
+### 3.3 Archive Location
+
+```
+project-guidelines/archive/
+  YYYY-MM/
+    archived-document.md
+```
+
+### 3.4 Archive Process
+
+1. Move file to archive directory
+2. Add archive header with date and reason
+3. Update any references
+4. Remove from MASTER-INDEX.md
+
+---
+
+## 4. RFC Lifecycle
+
+### 4.1 States
+
+| State | Description |
+|-------|-------------|
+| DRAFT | Initial ideation, incomplete |
+| PROPOSED | Complete, open for feedback (14 days) |
+| ACCEPTED | Approved, ready for implementation |
+| IN_PROGRESS | Phases being executed |
+| COMPLETE | All phases implemented |
+| ABANDONED | Rejected or withdrawn |
+| DEPRECATED | Superseded by newer RFC |
+
+### 4.2 State Transitions
+
+```
+DRAFT -> PROPOSED -> ACCEPTED -> IN_PROGRESS -> COMPLETE
+                  \-> ABANDONED
+                               \-> DEPRECATED
+```
+
+### 4.3 Required Fields
+
+Every RFC must have:
+- Unique ID (RFC-XXX)
+- Title
+- Status
+- Author
+- Date
+- Target Version
+- Summary
+- Phases with status
+
+---
+
+## 5. Update Triggers
+
+### 5.1 After Workflow Completion
+
+Update:
+- RFC status (if applicable)
+- CHANGELOG.md
+- MASTER-INDEX.md
+- package.json version (if release)
+
+### 5.2 After New Feature
+
+Update:
+- docs/ with user documentation
+- README.md if major feature
+- CLAUDE.md if new skill/agent
+
+### 5.3 After Bug Fix
+
+Update:
+- CHANGELOG.md
+- Related tracking files
+
+---
+
+## 6. Required Files
+
+### 6.1 Root Level
+
+| File | Required | Description |
+|------|----------|-------------|
+| README.md | Yes | Project overview |
+| CLAUDE.md | Yes | LLM agent instructions |
+| CHANGELOG.md | Recommended | Version history |
+| package.json | Yes | Project metadata |
+
+### 6.2 project-guidelines/
+
+| File | Required | Description |
+|------|----------|-------------|
+| README.md | Yes | Guidelines overview |
+| MASTER-INDEX.md | Recommended | Navigation index |
+| rfcs/index.md | If RFCs exist | RFC listing |
+| adrs/index.md | If ADRs exist | ADR listing |
+
+### 6.3 docs/
+
+| File | Required | Description |
+|------|----------|-------------|
+| README.md | Yes | Documentation overview |
+| getting-started.md | Recommended | Quick start guide |
+
+---
+
+## 7. Naming Conventions
+
+### 7.1 Files
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| RFC | `RFC-XXX-TITLE.md` | RFC-001-REST-API.md |
+| ADR | `ADR-XXX-TITLE.md` | ADR-001-DATABASE.md |
+| Tracking | `PHASE{N}-TRACKING.md` | PHASE1-TRACKING.md |
+| Guide | `{topic}-guide.md` | authentication-guide.md |
+| Tutorial | `{topic}-tutorial.md` | getting-started-tutorial.md |
+
+### 7.2 Directories
+
+- Use lowercase with hyphens
+- No spaces or underscores
+- Descriptive names
+
+**Examples:**
+- `project-guidelines/` (not `projectGuidelines/`)
+- `getting-started/` (not `GettingStarted/`)
+
+---
+
+## 8. Compliance Checks
+
+The Documentation Guardian verifies:
+
+### 8.1 Errors (Must Fix)
+
+- Version mismatch between package.json and git tags
+- Missing required files
+- Invalid RFC/ADR structure
+
+### 8.2 Warnings (Should Fix)
+
+- Documents in wrong directory
+- Missing recommended files
+- Outdated references
+
+### 8.3 Infos (Consider)
+
+- Archive candidates
+- Old unmodified files
+- Completed tracking files
+
+---
+
+## References
+
+- [Semantic Versioning 2.0.0](https://semver.org/)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [RFC Process](https://en.wikipedia.org/wiki/Request_for_Comments)
+- [ADR Process](https://adr.github.io/)
+
+---
+
+**Generated for**: my-project
+**Template**: orchestrator
+**Constitution Preset**: orchestrator