dan/ops-jrz1
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Initialize ops-jrz1 repository with Matrix platform extraction foundation

Browse source 
- Add speckit workflow infrastructure (.claude, .specify)
- Create NixOS configuration skeleton (flake.nix, configuration.nix, hosts/ops-jrz1.nix)
- Add sanitization scripts with 22 rules for personal info removal
- Add validation scripts with gitleaks integration
- Configure git hooks (pre-commit, pre-push) for security validation
- Add project documentation (README, LICENSE)
- Add comprehensive .gitignore for Nix, secrets, staging

Phase 1 and Phase 2 complete. Foundation ready for module extraction from ops-base.
This commit is contained in:
Dan 2025-10-13 13:37:17 -07:00
commit 894e7241f1
42 changed files with 7741 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

184
.claude/commands/speckit.analyze.md Normal file
View file

@ -0,0 +1,184 @@
---
description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
---
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty).
## Goal
Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
## Operating Constraints
**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
## Execution Steps
### 1. Initialize Analysis Context
Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
- SPEC = FEATURE_DIR/spec.md
- PLAN = FEATURE_DIR/plan.md
- TASKS = FEATURE_DIR/tasks.md
Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
### 2. Load Artifacts (Progressive Disclosure)
Load only the minimal necessary context from each artifact:
**From spec.md:**
- Overview/Context
- Functional Requirements
- Non-Functional Requirements
- User Stories
- Edge Cases (if present)
**From plan.md:**
- Architecture/stack choices
- Data Model references
- Phases
- Technical constraints
**From tasks.md:**
- Task IDs
- Descriptions
- Phase grouping
- Parallel markers [P]
- Referenced file paths
**From constitution:**
- Load `.specify/memory/constitution.md` for principle validation
### 3. Build Semantic Models
Create internal representations (do not include raw artifacts in output):
- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
- **User story/action inventory**: Discrete user actions with acceptance criteria
- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
### 4. Detection Passes (Token-Efficient Analysis)
Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
#### A. Duplication Detection
- Identify near-duplicate requirements
- Mark lower-quality phrasing for consolidation
#### B. Ambiguity Detection
- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
#### C. Underspecification
- Requirements with verbs but missing object or measurable outcome
- User stories missing acceptance criteria alignment
- Tasks referencing files or components not defined in spec/plan
#### D. Constitution Alignment
- Any requirement or plan element conflicting with a MUST principle
- Missing mandated sections or quality gates from constitution
#### E. Coverage Gaps
- Requirements with zero associated tasks
- Tasks with no mapped requirement/story
- Non-functional requirements not reflected in tasks (e.g., performance, security)
#### F. Inconsistency
- Terminology drift (same concept named differently across files)
- Data entities referenced in plan but absent in spec (or vice versa)
- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
### 5. Severity Assignment
Use this heuristic to prioritize findings:
- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
### 6. Produce Compact Analysis Report
Output a Markdown report (no file writes) with the following structure:
## Specification Analysis Report
| ID | Category | Severity | Location(s) | Summary | Recommendation |
|----|----------|----------|-------------|---------|----------------|
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
(Add one row per finding; generate stable IDs prefixed by category initial.)
**Coverage Summary Table:**
| Requirement Key | Has Task? | Task IDs | Notes |
|-----------------|-----------|----------|-------|
**Constitution Alignment Issues:** (if any)
**Unmapped Tasks:** (if any)
**Metrics:**
- Total Requirements
- Total Tasks
- Coverage % (requirements with >=1 task)
- Ambiguity Count
- Duplication Count
- Critical Issues Count
### 7. Provide Next Actions
At end of report, output a concise Next Actions block:
- If CRITICAL issues exist: Recommend resolving before `/implement`
- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
- Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
### 8. Offer Remediation
Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
## Operating Principles
### Context Efficiency
- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
### Analysis Guidelines
- **NEVER modify files** (this is read-only analysis)
- **NEVER hallucinate missing sections** (if absent, report them accurately)
- **Prioritize constitution violations** (these are always CRITICAL)
- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
- **Report zero issues gracefully** (emit success report with coverage statistics)
## Context
$ARGUMENTS

287
.claude/commands/speckit.checklist.md Normal file
View file

@ -0,0 +1,287 @@
---
description: Generate a custom checklist for the current feature based on user requirements.
---
## Checklist Purpose: "Unit Tests for English"
**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
**NOT for verification/testing**:
- ❌ NOT "Verify the button clicks correctly"
- ❌ NOT "Test error handling works"
- ❌ NOT "Confirm the API returns 200"
- ❌ NOT checking if code/implementation matches the spec
**FOR requirements quality validation**:
- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty).
## Execution Steps
1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
- All file paths must be absolute.
- For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
- Be generated from the user's phrasing + extracted signals from spec/plan/tasks
- Only ask about information that materially changes checklist content
- Be skipped individually if already unambiguous in `$ARGUMENTS`
- Prefer precision over breadth
Generation algorithm:
1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
5. Formulate questions chosen from these archetypes:
- Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
- Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
- Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
- Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
- Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
- Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
Question formatting rules:
- If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
- Limit to A–E options maximum; omit table if a free-form answer is clearer
- Never ask the user to restate what they already said
- Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
Defaults when interaction impossible:
- Depth: Standard
- Audience: Reviewer (PR) if code-related; Author otherwise
- Focus: Top 2 relevance clusters
Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
- Derive checklist theme (e.g., security, review, deploy, ux)
- Consolidate explicit must-have items mentioned by user
- Map focus selections to category scaffolding
- Infer any missing context from spec/plan/tasks (do NOT hallucinate)
4. **Load feature context**: Read from FEATURE_DIR:
- spec.md: Feature requirements and scope
- plan.md (if exists): Technical details, dependencies
- tasks.md (if exists): Implementation tasks
**Context Loading Strategy**:
- Load only necessary portions relevant to active focus areas (avoid full-file dumping)
- Prefer summarizing long sections into concise scenario/requirement bullets
- Use progressive disclosure: add follow-on retrieval only if gaps detected
- If source docs are large, generate interim summary items instead of embedding raw text
5. **Generate checklist** - Create "Unit Tests for Requirements":
- Create `FEATURE_DIR/checklists/` directory if it doesn't exist
- Generate unique checklist filename:
- Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
- Format: `[domain].md`
- If file exists, append to existing file
- Number items sequentially starting from CHK001
- Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists)
**CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
- **Completeness**: Are all necessary requirements present?
- **Clarity**: Are requirements unambiguous and specific?
- **Consistency**: Do requirements align with each other?
- **Measurability**: Can requirements be objectively verified?
- **Coverage**: Are all scenarios/edge cases addressed?
**Category Structure** - Group items by requirement quality dimensions:
- **Requirement Completeness** (Are all necessary requirements documented?)
- **Requirement Clarity** (Are requirements specific and unambiguous?)
- **Requirement Consistency** (Do requirements align without conflicts?)
- **Acceptance Criteria Quality** (Are success criteria measurable?)
- **Scenario Coverage** (Are all flows/cases addressed?)
- **Edge Case Coverage** (Are boundary conditions defined?)
- **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
- **Dependencies & Assumptions** (Are they documented and validated?)
- **Ambiguities & Conflicts** (What needs clarification?)
**HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
❌ **WRONG** (Testing implementation):
- "Verify landing page displays 3 episode cards"
- "Test hover states work on desktop"
- "Confirm logo click navigates home"
✅ **CORRECT** (Testing requirements quality):
- "Are the exact number and layout of featured episodes specified?" [Completeness]
- "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
- "Are hover state requirements consistent across all interactive elements?" [Consistency]
- "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
- "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
- "Are loading states defined for asynchronous episode data?" [Completeness]
- "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
**ITEM STRUCTURE**:
Each item should follow this pattern:
- Question format asking about requirement quality
- Focus on what's WRITTEN (or not written) in the spec/plan
- Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
- Reference spec section `[Spec §X.Y]` when checking existing requirements
- Use `[Gap]` marker when checking for missing requirements
**EXAMPLES BY QUALITY DIMENSION**:
Completeness:
- "Are error handling requirements defined for all API failure modes? [Gap]"
- "Are accessibility requirements specified for all interactive elements? [Completeness]"
- "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
Clarity:
- "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
- "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
- "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
Consistency:
- "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
- "Are card component requirements consistent between landing and detail pages? [Consistency]"
Coverage:
- "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
- "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
- "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
Measurability:
- "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
- "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
**Scenario Classification & Coverage** (Requirements Quality Focus):
- Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
- For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
- If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
- Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
**Traceability Requirements**:
- MINIMUM: ≥80% of items MUST include at least one traceability reference
- Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
- If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
**Surface & Resolve Issues** (Requirements Quality Problems):
Ask questions about the requirements themselves:
- Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
- Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
- Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
- Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
- Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
**Content Consolidation**:
- Soft cap: If raw candidate items > 40, prioritize by risk/impact
- Merge near-duplicates checking the same requirement aspect
- If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
**🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
- ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
- ❌ References to code execution, user actions, system behavior
- ❌ "Displays correctly", "works properly", "functions as expected"
- ❌ "Click", "navigate", "render", "load", "execute"
- ❌ Test cases, test plans, QA procedures
- ❌ Implementation details (frameworks, APIs, algorithms)
**✅ REQUIRED PATTERNS** - These test requirements quality:
- ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
- ✅ "Is [vague term] quantified/clarified with specific criteria?"
- ✅ "Are requirements consistent between [section A] and [section B]?"
- ✅ "Can [requirement] be objectively measured/verified?"
- ✅ "Are [edge cases/scenarios] addressed in requirements?"
- ✅ "Does the spec define [missing aspect]?"
6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize:
- Focus areas selected
- Depth level
- Actor/timing
- Any explicit user-specified must-have items incorporated
**Important**: Each `/speckit.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows:
- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
- Simple, memorable filenames that indicate checklist purpose
- Easy identification and navigation in the `checklists/` folder
To avoid clutter, use descriptive types and clean up obsolete checklists when done.
## Example Checklist Types & Sample Items
**UX Requirements Quality:** `ux.md`
Sample items (testing the requirements, NOT the implementation):
- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
**API Requirements Quality:** `api.md`
Sample items:
- "Are error response formats specified for all failure scenarios? [Completeness]"
- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
- "Are authentication requirements consistent across all endpoints? [Consistency]"
- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
- "Is versioning strategy documented in requirements? [Gap]"
**Performance Requirements Quality:** `performance.md`
Sample items:
- "Are performance requirements quantified with specific metrics? [Clarity]"
- "Are performance targets defined for all critical user journeys? [Coverage]"
- "Are performance requirements under different load conditions specified? [Completeness]"
- "Can performance requirements be objectively measured? [Measurability]"
- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
**Security Requirements Quality:** `security.md`
Sample items:
- "Are authentication requirements specified for all protected resources? [Coverage]"
- "Are data protection requirements defined for sensitive information? [Completeness]"
- "Is the threat model documented and requirements aligned to it? [Traceability]"
- "Are security requirements consistent with compliance obligations? [Consistency]"
- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
## Anti-Examples: What NOT To Do
**❌ WRONG - These test implementation, not requirements:**
```markdown
- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
```
**✅ CORRECT - These test requirements quality:**
```markdown
- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
```
**Key Differences:**
- Wrong: Tests if the system works correctly
- Correct: Tests if the requirements are written correctly
- Wrong: Verification of behavior
- Correct: Validation of requirement quality
- Wrong: "Does it do X?"
- Correct: "Is X clearly specified?"

176
.claude/commands/speckit.clarify.md Normal file
View file

@ -0,0 +1,176 @@
---
description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
---
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty).
## Outline
Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
Execution steps:
1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
- `FEATURE_DIR`
- `FEATURE_SPEC`
- (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
- If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment.
- For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
Functional Scope & Behavior:
- Core user goals & success criteria
- Explicit out-of-scope declarations
- User roles / personas differentiation
Domain & Data Model:
- Entities, attributes, relationships
- Identity & uniqueness rules
- Lifecycle/state transitions
- Data volume / scale assumptions
Interaction & UX Flow:
- Critical user journeys / sequences
- Error/empty/loading states
- Accessibility or localization notes
Non-Functional Quality Attributes:
- Performance (latency, throughput targets)
- Scalability (horizontal/vertical, limits)
- Reliability & availability (uptime, recovery expectations)
- Observability (logging, metrics, tracing signals)
- Security & privacy (authN/Z, data protection, threat assumptions)
- Compliance / regulatory constraints (if any)
Integration & External Dependencies:
- External services/APIs and failure modes
- Data import/export formats
- Protocol/versioning assumptions
Edge Cases & Failure Handling:
- Negative scenarios
- Rate limiting / throttling
- Conflict resolution (e.g., concurrent edits)
Constraints & Tradeoffs:
- Technical constraints (language, storage, hosting)
- Explicit tradeoffs or rejected alternatives
Terminology & Consistency:
- Canonical glossary terms
- Avoided synonyms / deprecated terms
Completion Signals:
- Acceptance criteria testability
- Measurable Definition of Done style indicators
Misc / Placeholders:
- TODO markers / unresolved decisions
- Ambiguous adjectives ("robust", "intuitive") lacking quantification
For each category with Partial or Missing status, add a candidate question opportunity unless:
- Clarification would not materially change implementation or validation strategy
- Information is better deferred to planning phase (note internally)
3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
- Maximum of 10 total questions across the whole session.
- Each question must be answerable with EITHER:
* A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
* A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
- Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
- Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
- Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
- Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
- If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
4. Sequential questioning loop (interactive):
- Present EXACTLY ONE question at a time.
- For multiple‑choice questions:
* **Analyze all options** and determine the **most suitable option** based on:
- Best practices for the project type
- Common patterns in similar implementations
- Risk reduction (security, performance, maintainability)
- Alignment with any explicit project goals or constraints visible in the spec
* Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
* Format as: `**Recommended:** Option [X] - <reasoning>`
* Then render all options as a Markdown table:
| Option | Description |
|--------|-------------|
| A | <Option A description> |
| B | <Option B description> |
| C | <Option C description> | (add D/E as needed up to 5)
| Short | Provide a different short answer (<=5 words) | (Include only if free-form alternative is appropriate)
* After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
- For short‑answer style (no meaningful discrete options):
* Provide your **suggested answer** based on best practices and context.
* Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
* Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
- After the user answers:
* If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
* Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
* If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
* Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
- Stop asking further questions when:
* All critical ambiguities resolved early (remaining queued items become unnecessary), OR
* User signals completion ("done", "good", "no more"), OR
* You reach 5 asked questions.
- Never reveal future queued questions in advance.
- If no valid questions exist at start, immediately report no critical ambiguities.
5. Integration after EACH accepted answer (incremental update approach):
- Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
- For the first integrated answer in this session:
* Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
* Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
- Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
- Then immediately apply the clarification to the most appropriate section(s):
* Functional ambiguity → Update or add a bullet in Functional Requirements.
* User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
* Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
* Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
* Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
* Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
- If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
- Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
- Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
- Keep each inserted clarification minimal and testable (avoid narrative drift).
6. Validation (performed after EACH write plus final pass):
- Clarifications session contains exactly one bullet per accepted answer (no duplicates).
- Total asked (accepted) questions ≤ 5.
- Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
- No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
- Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
- Terminology consistency: same canonical term used across all updated sections.
7. Write the updated spec back to `FEATURE_SPEC`.
8. Report completion (after questioning loop ends or early termination):
- Number of questions asked & answered.
- Path to updated spec.
- Sections touched (list names).
- Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
- If any Outstanding or Deferred remain, recommend whether to proceed to `/speckit.plan` or run `/speckit.clarify` again later post-plan.
- Suggested next command.
Behavior rules:
- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
- If spec file missing, instruct user to run `/speckit.specify` first (do not create a new spec here).
- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
- Avoid speculative tech stack questions unless the absence blocks functional clarity.
- Respect user early termination signals ("stop", "done", "proceed").
- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
Context for prioritization: $ARGUMENTS

77
.claude/commands/speckit.constitution.md Normal file
View file

@ -0,0 +1,77 @@
---
description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
---
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty).
## Outline
You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
Follow this execution flow:
1. Load the existing constitution template at `.specify/memory/constitution.md`.
- Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
**IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
2. Collect/derive values for placeholders:
- If user input (conversation) supplies a value, use it.
- Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
- For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
- `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
* MAJOR: Backward incompatible governance/principle removals or redefinitions.
* MINOR: New principle/section added or materially expanded guidance.
* PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
- If version bump type ambiguous, propose reasoning before finalizing.
3. Draft the updated constitution content:
- Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
- Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
- Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
- Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
4. Consistency propagation checklist (convert prior checklist into active validations):
- Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
- Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
- Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
- Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
- Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
- Version change: old → new
- List of modified principles (old title → new title if renamed)
- Added sections
- Removed sections
- Templates requiring updates (✅ updated / ⚠ pending) with file paths
- Follow-up TODOs if any placeholders intentionally deferred.
6. Validation before final output:
- No remaining unexplained bracket tokens.
- Version line matches report.
- Dates ISO format YYYY-MM-DD.
- Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
8. Output a final summary to the user with:
- New version and bump rationale.
- Any files flagged for manual follow-up.
- Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
Formatting & Style Requirements:
- Use Markdown headings exactly as in the template (do not demote/promote levels).
- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
- Keep a single blank line between sections.
- Avoid trailing whitespace.
If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.

122
.claude/commands/speckit.implement.md Normal file
View file

@ -0,0 +1,122 @@
---
description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
---
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty).
## Outline
1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
- Scan all checklist files in the checklists/ directory
- For each checklist, count:
* Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
* Completed items: Lines matching `- [X]` or `- [x]`
* Incomplete items: Lines matching `- [ ]`
- Create a status table:
```
| Checklist | Total | Completed | Incomplete | Status |
|-----------|-------|-----------|------------|--------|
| ux.md | 12 | 12 | 0 | ✓ PASS |
| test.md | 8 | 5 | 3 | ✗ FAIL |
| security.md | 6 | 6 | 0 | ✓ PASS |
```
- Calculate overall status:
* **PASS**: All checklists have 0 incomplete items
* **FAIL**: One or more checklists have incomplete items
- **If any checklist is incomplete**:
* Display the table with incomplete item counts
* **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
* Wait for user response before continuing
* If user says "no" or "wait" or "stop", halt execution
* If user says "yes" or "proceed" or "continue", proceed to step 3
- **If all checklists are complete**:
* Display the table showing all checklists passed
* Automatically proceed to step 3
3. Load and analyze the implementation context:
- **REQUIRED**: Read tasks.md for the complete task list and execution plan
- **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
- **IF EXISTS**: Read data-model.md for entities and relationships
- **IF EXISTS**: Read contracts/ for API specifications and test requirements
- **IF EXISTS**: Read research.md for technical decisions and constraints
- **IF EXISTS**: Read quickstart.md for integration scenarios
4. **Project Setup Verification**:
- **REQUIRED**: Create/verify ignore files based on actual project setup:
**Detection & Creation Logic**:
- Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
```sh
git rev-parse --git-dir 2>/dev/null
```
- Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
- Check if .eslintrc* or eslint.config.* exists → create/verify .eslintignore
- Check if .prettierrc* exists → create/verify .prettierignore
- Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
- Check if terraform files (*.tf) exist → create/verify .terraformignore
- Check if .helmignore needed (helm charts present) → create/verify .helmignore
**If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
**If ignore file missing**: Create with full pattern set for detected technology
**Common Patterns by Technology** (from plan.md tech stack):
- **Node.js/JavaScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
- **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
- **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
- **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
- **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
- **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
**Tool-Specific Patterns**:
- **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
- **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
- **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
- **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
5. Parse tasks.md structure and extract:
- **Task phases**: Setup, Tests, Core, Integration, Polish
- **Task dependencies**: Sequential vs parallel execution rules
- **Task details**: ID, description, file paths, parallel markers [P]
- **Execution flow**: Order and dependency requirements
6. Execute implementation following the task plan:
- **Phase-by-phase execution**: Complete each phase before moving to the next
- **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together
- **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
- **File-based coordination**: Tasks affecting the same files must run sequentially
- **Validation checkpoints**: Verify each phase completion before proceeding
7. Implementation execution rules:
- **Setup first**: Initialize project structure, dependencies, configuration
- **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
- **Core development**: Implement models, services, CLI commands, endpoints
- **Integration work**: Database connections, middleware, logging, external services
- **Polish and validation**: Unit tests, performance optimization, documentation
8. Progress tracking and error handling:
- Report progress after each completed task
- Halt execution if any non-parallel task fails
- For parallel tasks [P], continue with successful tasks, report failed ones
- Provide clear error messages with context for debugging
- Suggest next steps if implementation cannot proceed
- **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
9. Completion validation:
- Verify all required tasks are completed
- Check that implemented features match the original specification
- Validate that tests pass and coverage meets requirements
- Confirm the implementation follows the technical plan
- Report final status with summary of completed work
Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/tasks` first to regenerate the task list.

80
.claude/commands/speckit.plan.md Normal file
View file

@ -0,0 +1,80 @@
---
description: Execute the implementation planning workflow using the plan template to generate design artifacts.
---
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty).
## Outline
1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
2. **Load context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
- Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
- Fill Constitution Check section from constitution
- Evaluate gates (ERROR if violations unjustified)
- Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
- Phase 1: Generate data-model.md, contracts/, quickstart.md
- Phase 1: Update agent context by running the agent script
- Re-evaluate Constitution Check post-design
4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
## Phases
### Phase 0: Outline & Research
1. **Extract unknowns from Technical Context** above:
- For each NEEDS CLARIFICATION → research task
- For each dependency → best practices task
- For each integration → patterns task
2. **Generate and dispatch research agents**:
```
For each unknown in Technical Context:
Task: "Research {unknown} for {feature context}"
For each technology choice:
Task: "Find best practices for {tech} in {domain}"
```
3. **Consolidate findings** in `research.md` using format:
- Decision: [what was chosen]
- Rationale: [why chosen]
- Alternatives considered: [what else evaluated]
**Output**: research.md with all NEEDS CLARIFICATION resolved
### Phase 1: Design & Contracts
**Prerequisites:** `research.md` complete
1. **Extract entities from feature spec** → `data-model.md`:
- Entity name, fields, relationships
- Validation rules from requirements
- State transitions if applicable
2. **Generate API contracts** from functional requirements:
- For each user action → endpoint
- Use standard REST/GraphQL patterns
- Output OpenAPI/GraphQL schema to `/contracts/`
3. **Agent context update**:
- Run `.specify/scripts/bash/update-agent-context.sh claude`
- These scripts detect which AI agent is in use
- Update the appropriate agent-specific context file
- Add only new technology from current plan
- Preserve manual additions between markers
**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
## Key rules
- Use absolute paths
- ERROR on gate failures or unresolved clarifications

208
.claude/commands/speckit.specify.md Normal file
View file

@ -0,0 +1,208 @@
---
description: Create or update the feature specification from a natural language feature description.
---
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty).
## Outline
The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
Given that feature description, do this:
1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
**IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
2. Load `.specify/templates/spec-template.md` to understand required sections.
3. Follow this execution flow:
1. Parse user description from Input
If empty: ERROR "No feature description provided"
2. Extract key concepts from description
Identify: actors, actions, data, constraints
3. For unclear aspects:
- Make informed guesses based on context and industry standards
- Only mark with [NEEDS CLARIFICATION: specific question] if:
- The choice significantly impacts feature scope or user experience
- Multiple reasonable interpretations exist with different implications
- No reasonable default exists
- **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
- Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
4. Fill User Scenarios & Testing section
If no clear user flow: ERROR "Cannot determine user scenarios"
5. Generate Functional Requirements
Each requirement must be testable
Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
6. Define Success Criteria
Create measurable, technology-agnostic outcomes
Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
Each criterion must be verifiable without implementation details
7. Identify Key Entities (if data involved)
8. Return: SUCCESS (spec ready for planning)
4. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
5. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
```markdown
# Specification Quality Checklist: [FEATURE NAME]
**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: [DATE]
**Feature**: [Link to spec.md]
## Content Quality
- [ ] No implementation details (languages, frameworks, APIs)
- [ ] Focused on user value and business needs
- [ ] Written for non-technical stakeholders
- [ ] All mandatory sections completed
## Requirement Completeness
- [ ] No [NEEDS CLARIFICATION] markers remain
- [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable
- [ ] Success criteria are technology-agnostic (no implementation details)
- [ ] All acceptance scenarios are defined
- [ ] Edge cases are identified
- [ ] Scope is clearly bounded
- [ ] Dependencies and assumptions identified
## Feature Readiness
- [ ] All functional requirements have clear acceptance criteria
- [ ] User scenarios cover primary flows
- [ ] Feature meets measurable outcomes defined in Success Criteria
- [ ] No implementation details leak into specification
## Notes
- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`
```
b. **Run Validation Check**: Review the spec against each checklist item:
- For each item, determine if it passes or fails
- Document specific issues found (quote relevant spec sections)
c. **Handle Validation Results**:
- **If all items pass**: Mark checklist complete and proceed to step 6
- **If items fail (excluding [NEEDS CLARIFICATION])**:
1. List the failing items and specific issues
2. Update the spec to address each issue
3. Re-run validation until all items pass (max 3 iterations)
4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
- **If [NEEDS CLARIFICATION] markers remain**:
1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
3. For each clarification needed (max 3), present options to user in this format:
```markdown
## Question [N]: [Topic]
**Context**: [Quote relevant spec section]
**What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
**Suggested Answers**:
| Option | Answer | Implications |
|--------|--------|--------------|
| A | [First suggested answer] | [What this means for the feature] |
| B | [Second suggested answer] | [What this means for the feature] |
| C | [Third suggested answer] | [What this means for the feature] |
| Custom | Provide your own answer | [Explain how to provide custom input] |
**Your choice**: _[Wait for user response]_
```
4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
- Use consistent spacing with pipes aligned
- Each cell should have spaces around content: `| Content |` not `|Content|`
- Header separator must have at least 3 dashes: `|--------|`
- Test that the table renders correctly in markdown preview
5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
6. Present all questions together before waiting for responses
7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
9. Re-run validation after all clarifications are resolved
d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
6. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/speckit.clarify` or `/speckit.plan`).
**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
## General Guidelines
## Quick Guidelines
- Focus on **WHAT** users need and **WHY**.
- Avoid HOW to implement (no tech stack, APIs, code structure).
- Written for business stakeholders, not developers.
- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
### Section Requirements
- **Mandatory sections**: Must be completed for every feature
- **Optional sections**: Include only when relevant to the feature
- When a section doesn't apply, remove it entirely (don't leave as "N/A")
### For AI Generation
When creating this spec from a user prompt:
1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
2. **Document assumptions**: Record reasonable defaults in the Assumptions section
3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
- Significantly impact feature scope or user experience
- Have multiple reasonable interpretations with different implications
- Lack any reasonable default
4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
6. **Common areas needing clarification** (only if no reasonable default exists):
- Feature scope and boundaries (include/exclude specific use cases)
- User types and permissions (if multiple conflicting interpretations possible)
- Security/compliance requirements (when legally/financially significant)
**Examples of reasonable defaults** (don't ask about these):
- Data retention: Industry-standard practices for the domain
- Performance targets: Standard web/mobile app expectations unless specified
- Error handling: User-friendly messages with appropriate fallbacks
- Authentication method: Standard session-based or OAuth2 for web apps
- Integration patterns: RESTful APIs unless specified otherwise
### Success Criteria Guidelines
Success criteria must be:
1. **Measurable**: Include specific metrics (time, percentage, count, rate)
2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
3. **User-focused**: Describe outcomes from user/business perspective, not system internals
4. **Verifiable**: Can be tested/validated without knowing implementation details
**Good examples**:
- "Users can complete checkout in under 3 minutes"
- "System supports 10,000 concurrent users"
- "95% of searches return results in under 1 second"
- "Task completion rate improves by 40%"
**Bad examples** (implementation-focused):
- "API response time is under 200ms" (too technical, use "Users see results instantly")
- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
- "React components render efficiently" (framework-specific)
- "Redis cache hit rate above 80%" (technology-specific)

111
.claude/commands/speckit.tasks.md Normal file
View file

@ -0,0 +1,111 @@
---
description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
---
## User Input
```text
$ARGUMENTS
```
You **MUST** consider the user input before proceeding (if not empty).
## Outline
1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
2. **Load design documents**: Read from FEATURE_DIR:
- **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
- **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
- Note: Not all projects have all documents. Generate tasks based on what's available.
3. **Execute task generation workflow** (follow the template structure):
- Load plan.md and extract tech stack, libraries, project structure
- **Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)**
- If data-model.md exists: Extract entities → map to user stories
- If contracts/ exists: Each file → map endpoints to user stories
- If research.md exists: Extract decisions → generate setup tasks
- **Generate tasks ORGANIZED BY USER STORY**:
- Setup tasks (shared infrastructure needed by all stories)
- **Foundational tasks (prerequisites that must complete before ANY user story can start)**
- For each user story (in priority order P1, P2, P3...):
- Group all tasks needed to complete JUST that story
- Include models, services, endpoints, UI components specific to that story
- Mark which tasks are [P] parallelizable
- If tests requested: Include tests specific to that story
- Polish/Integration tasks (cross-cutting concerns)
- **Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature spec or user asks for TDD approach
- Apply task rules:
- Different files = mark [P] for parallel
- Same file = sequential (no [P])
- If tests requested: Tests before implementation (TDD order)
- Number tasks sequentially (T001, T002...)
- Generate dependency graph showing user story completion order
- Create parallel execution examples per user story
- Validate task completeness (each user story has all needed tasks, independently testable)
4. **Generate tasks.md**: Use `.specify.specify/templates/tasks-template.md` as structure, fill with:
- Correct feature name from plan.md
- Phase 1: Setup tasks (project initialization)
- Phase 2: Foundational tasks (blocking prerequisites for all user stories)
- Phase 3+: One phase per user story (in priority order from spec.md)
- Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
- Clear [Story] labels (US1, US2, US3...) for each task
- [P] markers for parallelizable tasks within each story
- Checkpoint markers after each story phase
- Final Phase: Polish & cross-cutting concerns
- Numbered tasks (T001, T002...) in execution order
- Clear file paths for each task
- Dependencies section showing story completion order
- Parallel execution examples per story
- Implementation strategy section (MVP first, incremental delivery)
5. **Report**: Output path to generated tasks.md and summary:
- Total task count
- Task count per user story
- Parallel opportunities identified
- Independent test criteria for each story
- Suggested MVP scope (typically just User Story 1)
Context for task generation: $ARGUMENTS
The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
## Task Generation Rules
**IMPORTANT**: Tests are optional. Only generate test tasks if the user explicitly requested testing or TDD approach in the feature specification.
**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
- Each user story (P1, P2, P3...) gets its own phase
- Map all related components to their story:
- Models needed for that story
- Services needed for that story
- Endpoints/UI needed for that story
- If tests requested: Tests specific to that story
- Mark story dependencies (most stories should be independent)
2. **From Contracts**:
- Map each contract/endpoint → to the user story it serves
- If tests requested: Each contract → contract test task [P] before implementation in that story's phase
3. **From Data Model**:
- Map each entity → to the user story(ies) that need it
- If entity serves multiple stories: Put in earliest story or Setup phase
- Relationships → service layer tasks in appropriate story phase
4. **From Setup/Infrastructure**:
- Shared infrastructure → Setup phase (Phase 1)
- Foundational/blocking tasks → Foundational phase (Phase 2)
- Examples: Database schema setup, authentication framework, core libraries, base configurations
- These MUST complete before any user story can be implemented
- Story-specific setup → within that story's phase
5. **Ordering**:
- Phase 1: Setup (project initialization)
- Phase 2: Foundational (blocking prerequisites - must complete before user stories)
- Phase 3+: User Stories in priority order (P1, P2, P3...)
- Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
- Final Phase: Polish & Cross-Cutting Concerns
- Each user story phase should be a complete, independently testable increment

40
.gitignore vendored Normal file
View file

@ -0,0 +1,40 @@
# Nix build outputs
result
result-*
# Staging directories (temporary extraction workspace)
staging/
# Secrets (never commit real secrets)
secrets/*.yaml
!secrets/*.example
*.age
.sops.yaml
!.sops.yaml.example
# Temporary files
*.tmp
*.swp
*.bak
*~
# OS-specific
.DS_Store
Thumbs.db
# Editor directories
.vscode/
.idea/
*.sublime-*
# Logs
*.log
# Python (if any helper scripts)
__pycache__/
*.pyc
.venv/
venv/
# Bash script temporaries
.bash_history

54
.pre-commit-config.yaml Normal file
View file

@ -0,0 +1,54 @@
# Pre-commit hooks for ops-jrz1 Matrix platform repository
# Install: pre-commit install
# Run manually: pre-commit run --all-files
repos:
# Nix formatting and linting
- repo: https://github.com/nix-community/nixpkgs-fmt
rev: v1.3.0
hooks:
- id: nixpkgs-fmt
# Secret scanning with gitleaks
- repo: https://github.com/gitleaks/gitleaks
rev: v8.18.0
hooks:
- id: gitleaks
# General file checks
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-files
args: ['--maxkb=500']
- id: check-merge-conflict
# Custom hooks for ops-jrz1
- repo: local
hooks:
# Validate sanitization before commit
- id: validate-sanitization
name: Validate sanitization rules
entry: scripts/hooks/validate-sanitization-hook.sh
language: script
files: '\.(nix|md)$'
pass_filenames: false
# Nix flake check (expensive, runs on pre-push)
- id: nix-flake-check
name: Nix flake check
entry: scripts/hooks/nix-flake-check-hook.sh
language: script
stages: [push]
pass_filenames: false
# Build validation (expensive, runs on pre-push)
- id: nix-build-validation
name: Nix build validation
entry: scripts/hooks/nix-build-hook.sh
language: script
stages: [push]
pass_filenames: false

50
.specify/memory/constitution.md Normal file
View file

@ -0,0 +1,50 @@
# [PROJECT_NAME] Constitution
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
## Core Principles
### [PRINCIPLE_1_NAME]
<!-- Example: I. Library-First -->
[PRINCIPLE_1_DESCRIPTION]
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
### [PRINCIPLE_2_NAME]
<!-- Example: II. CLI Interface -->
[PRINCIPLE_2_DESCRIPTION]
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
### [PRINCIPLE_3_NAME]
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
[PRINCIPLE_3_DESCRIPTION]
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
### [PRINCIPLE_4_NAME]
<!-- Example: IV. Integration Testing -->
[PRINCIPLE_4_DESCRIPTION]
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
### [PRINCIPLE_5_NAME]
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
[PRINCIPLE_5_DESCRIPTION]
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
## [SECTION_2_NAME]
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
[SECTION_2_CONTENT]
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
## [SECTION_3_NAME]
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
[SECTION_3_CONTENT]
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
## Governance
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
[GOVERNANCE_RULES]
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

166
.specify/scripts/bash/check-prerequisites.sh Executable file
View file

@ -0,0 +1,166 @@
#!/usr/bin/env bash
# Consolidated prerequisite checking script
#
# This script provides unified prerequisite checking for Spec-Driven Development workflow.
# It replaces the functionality previously spread across multiple scripts.
#
# Usage: ./check-prerequisites.sh [OPTIONS]
#
# OPTIONS:
# --json Output in JSON format
# --require-tasks Require tasks.md to exist (for implementation phase)
# --include-tasks Include tasks.md in AVAILABLE_DOCS list
# --paths-only Only output path variables (no validation)
# --help, -h Show help message
#
# OUTPUTS:
# JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
# Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
# Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
set -e
# Parse command line arguments
JSON_MODE=false
REQUIRE_TASKS=false
INCLUDE_TASKS=false
PATHS_ONLY=false
for arg in "$@"; do
case "$arg" in
--json)
JSON_MODE=true
;;
--require-tasks)
REQUIRE_TASKS=true
;;
--include-tasks)
INCLUDE_TASKS=true
;;
--paths-only)
PATHS_ONLY=true
;;
--help|-h)
cat << 'EOF'
Usage: check-prerequisites.sh [OPTIONS]
Consolidated prerequisite checking for Spec-Driven Development workflow.
OPTIONS:
--json Output in JSON format
--require-tasks Require tasks.md to exist (for implementation phase)
--include-tasks Include tasks.md in AVAILABLE_DOCS list
--paths-only Only output path variables (no prerequisite validation)
--help, -h Show this help message
EXAMPLES:
# Check task prerequisites (plan.md required)
./check-prerequisites.sh --json
# Check implementation prerequisites (plan.md + tasks.md required)
./check-prerequisites.sh --json --require-tasks --include-tasks
# Get feature paths only (no validation)
./check-prerequisites.sh --paths-only
EOF
exit 0
;;
*)
echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
exit 1
;;
esac
done
# Source common functions
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/common.sh"
# Get feature paths and validate branch
eval $(get_feature_paths)
check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
# If paths-only mode, output paths and exit (support JSON + paths-only combined)
if $PATHS_ONLY; then
if $JSON_MODE; then
# Minimal JSON paths payload (no validation performed)
printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
"$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
else
echo "REPO_ROOT: $REPO_ROOT"
echo "BRANCH: $CURRENT_BRANCH"
echo "FEATURE_DIR: $FEATURE_DIR"
echo "FEATURE_SPEC: $FEATURE_SPEC"
echo "IMPL_PLAN: $IMPL_PLAN"
echo "TASKS: $TASKS"
fi
exit 0
fi
# Validate required directories and files
if [[ ! -d "$FEATURE_DIR" ]]; then
echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
echo "Run /speckit.specify first to create the feature structure." >&2
exit 1
fi
if [[ ! -f "$IMPL_PLAN" ]]; then
echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
echo "Run /speckit.plan first to create the implementation plan." >&2
exit 1
fi
# Check for tasks.md if required
if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
echo "Run /speckit.tasks first to create the task list." >&2
exit 1
fi
# Build list of available documents
docs=()
# Always check these optional docs
[[ -f "$RESEARCH" ]] && docs+=("research.md")
[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
# Check contracts directory (only if it exists and has files)
if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
docs+=("contracts/")
fi
[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
# Include tasks.md if requested and it exists
if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
docs+=("tasks.md")
fi
# Output results
if $JSON_MODE; then
# Build JSON array of documents
if [[ ${#docs[@]} -eq 0 ]]; then
json_docs="[]"
else
json_docs=$(printf '"%s",' "${docs[@]}")
json_docs="[${json_docs%,}]"
fi
printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
else
# Text output
echo "FEATURE_DIR:$FEATURE_DIR"
echo "AVAILABLE_DOCS:"
# Show status of each potential document
check_file "$RESEARCH" "research.md"
check_file "$DATA_MODEL" "data-model.md"
check_dir "$CONTRACTS_DIR" "contracts/"
check_file "$QUICKSTART" "quickstart.md"
if $INCLUDE_TASKS; then
check_file "$TASKS" "tasks.md"
fi
fi

113
.specify/scripts/bash/common.sh Executable file
View file

@ -0,0 +1,113 @@
#!/usr/bin/env bash
# Common functions and variables for all scripts
# Get repository root, with fallback for non-git repositories
get_repo_root() {
if git rev-parse --show-toplevel >/dev/null 2>&1; then
git rev-parse --show-toplevel
else
# Fall back to script location for non-git repos
local script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
(cd "$script_dir/../../.." && pwd)
fi
}
# Get current branch, with fallback for non-git repositories
get_current_branch() {
# First check if SPECIFY_FEATURE environment variable is set
if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
echo "$SPECIFY_FEATURE"
return
fi
# Then check git if available
if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
git rev-parse --abbrev-ref HEAD
return
fi
# For non-git repos, try to find the latest feature directory
local repo_root=$(get_repo_root)
local specs_dir="$repo_root/specs"
if [[ -d "$specs_dir" ]]; then
local latest_feature=""
local highest=0
for dir in "$specs_dir"/*; do
if [[ -d "$dir" ]]; then
local dirname=$(basename "$dir")
if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
local number=${BASH_REMATCH[1]}
number=$((10#$number))
if [[ "$number" -gt "$highest" ]]; then
highest=$number
latest_feature=$dirname
fi
fi
fi
done
if [[ -n "$latest_feature" ]]; then
echo "$latest_feature"
return
fi
fi
echo "main" # Final fallback
}
# Check if we have git available
has_git() {
git rev-parse --show-toplevel >/dev/null 2>&1
}
check_feature_branch() {
local branch="$1"
local has_git_repo="$2"
# For non-git repos, we can't enforce branch naming but still provide output
if [[ "$has_git_repo" != "true" ]]; then
echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
return 0
fi
if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
echo "Feature branches should be named like: 001-feature-name" >&2
return 1
fi
return 0
}
get_feature_dir() { echo "$1/specs/$2"; }
get_feature_paths() {
local repo_root=$(get_repo_root)
local current_branch=$(get_current_branch)
local has_git_repo="false"
if has_git; then
has_git_repo="true"
fi
local feature_dir=$(get_feature_dir "$repo_root" "$current_branch")
cat <<EOF
REPO_ROOT='$repo_root'
CURRENT_BRANCH='$current_branch'
HAS_GIT='$has_git_repo'
FEATURE_DIR='$feature_dir'
FEATURE_SPEC='$feature_dir/spec.md'
IMPL_PLAN='$feature_dir/plan.md'
TASKS='$feature_dir/tasks.md'
RESEARCH='$feature_dir/research.md'
DATA_MODEL='$feature_dir/data-model.md'
QUICKSTART='$feature_dir/quickstart.md'
CONTRACTS_DIR='$feature_dir/contracts'
EOF
}
check_file() { [[ -f "$1" ]] && echo " ✓ $2" || echo " ✗ $2"; }
check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo " ✓ $2" || echo " ✗ $2"; }

97
.specify/scripts/bash/create-new-feature.sh Executable file
View file

@ -0,0 +1,97 @@
#!/usr/bin/env bash
set -e
JSON_MODE=false
ARGS=()
for arg in "$@"; do
case "$arg" in
--json) JSON_MODE=true ;;
--help|-h) echo "Usage: $0 [--json] <feature_description>"; exit 0 ;;
*) ARGS+=("$arg") ;;
esac
done
FEATURE_DESCRIPTION="${ARGS[*]}"
if [ -z "$FEATURE_DESCRIPTION" ]; then
echo "Usage: $0 [--json] <feature_description>" >&2
exit 1
fi
# Function to find the repository root by searching for existing project markers
find_repo_root() {
local dir="$1"
while [ "$dir" != "/" ]; do
if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
echo "$dir"
return 0
fi
dir="$(dirname "$dir")"
done
return 1
}
# Resolve repository root. Prefer git information when available, but fall back
# to searching for repository markers so the workflow still functions in repositories that
# were initialised with --no-git.
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
if git rev-parse --show-toplevel >/dev/null 2>&1; then
REPO_ROOT=$(git rev-parse --show-toplevel)
HAS_GIT=true
else
REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
if [ -z "$REPO_ROOT" ]; then
echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
exit 1
fi
HAS_GIT=false
fi
cd "$REPO_ROOT"
SPECS_DIR="$REPO_ROOT/specs"
mkdir -p "$SPECS_DIR"
HIGHEST=0
if [ -d "$SPECS_DIR" ]; then
for dir in "$SPECS_DIR"/*; do
[ -d "$dir" ] || continue
dirname=$(basename "$dir")
number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
number=$((10#$number))
if [ "$number" -gt "$HIGHEST" ]; then HIGHEST=$number; fi
done
fi
NEXT=$((HIGHEST + 1))
FEATURE_NUM=$(printf "%03d" "$NEXT")
BRANCH_NAME=$(echo "$FEATURE_DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//')
WORDS=$(echo "$BRANCH_NAME" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//')
BRANCH_NAME="${FEATURE_NUM}-${WORDS}"
if [ "$HAS_GIT" = true ]; then
git checkout -b "$BRANCH_NAME"
else
>&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
fi
FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
mkdir -p "$FEATURE_DIR"
TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
SPEC_FILE="$FEATURE_DIR/spec.md"
if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
# Set the SPECIFY_FEATURE environment variable for the current session
export SPECIFY_FEATURE="$BRANCH_NAME"
if $JSON_MODE; then
printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
else
echo "BRANCH_NAME: $BRANCH_NAME"
echo "SPEC_FILE: $SPEC_FILE"
echo "FEATURE_NUM: $FEATURE_NUM"
echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
fi

60
.specify/scripts/bash/setup-plan.sh Executable file
View file

@ -0,0 +1,60 @@
#!/usr/bin/env bash
set -e
# Parse command line arguments
JSON_MODE=false
ARGS=()
for arg in "$@"; do
case "$arg" in
--json)
JSON_MODE=true
;;
--help|-h)
echo "Usage: $0 [--json]"
echo " --json Output results in JSON format"
echo " --help Show this help message"
exit 0
;;
*)
ARGS+=("$arg")
;;
esac
done
# Get script directory and load common functions
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/common.sh"
# Get all paths and variables from common functions
eval $(get_feature_paths)
# Check if we're on a proper feature branch (only for git repos)
check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
# Ensure the feature directory exists
mkdir -p "$FEATURE_DIR"
# Copy plan template if it exists
TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
if [[ -f "$TEMPLATE" ]]; then
cp "$TEMPLATE" "$IMPL_PLAN"
echo "Copied plan template to $IMPL_PLAN"
else
echo "Warning: Plan template not found at $TEMPLATE"
# Create a basic plan file if template doesn't exist
touch "$IMPL_PLAN"
fi
# Output results
if $JSON_MODE; then
printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
"$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT"
else
echo "FEATURE_SPEC: $FEATURE_SPEC"
echo "IMPL_PLAN: $IMPL_PLAN"
echo "SPECS_DIR: $FEATURE_DIR"
echo "BRANCH: $CURRENT_BRANCH"
echo "HAS_GIT: $HAS_GIT"
fi

738
.specify/scripts/bash/update-agent-context.sh Executable file
View file

@ -0,0 +1,738 @@
#!/usr/bin/env bash
# Update agent context files with information from plan.md
#
# This script maintains AI agent context files by parsing feature specifications
# and updating agent-specific configuration files with project information.
#
# MAIN FUNCTIONS:
# 1. Environment Validation
# - Verifies git repository structure and branch information
# - Checks for required plan.md files and templates
# - Validates file permissions and accessibility
#
# 2. Plan Data Extraction
# - Parses plan.md files to extract project metadata
# - Identifies language/version, frameworks, databases, and project types
# - Handles missing or incomplete specification data gracefully
#
# 3. Agent File Management
# - Creates new agent context files from templates when needed
# - Updates existing agent files with new project information
# - Preserves manual additions and custom configurations
# - Supports multiple AI agent formats and directory structures
#
# 4. Content Generation
# - Generates language-specific build/test commands
# - Creates appropriate project directory structures
# - Updates technology stacks and recent changes sections
# - Maintains consistent formatting and timestamps
#
# 5. Multi-Agent Support
# - Handles agent-specific file paths and naming conventions
# - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, or Amazon Q Developer CLI
# - Can update single agents or all existing agent files
# - Creates default Claude file if no agent files exist
#
# Usage: ./update-agent-context.sh [agent_type]
# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|q
# Leave empty to update all existing agent files
set -e
# Enable strict error handling
set -u
set -o pipefail
#==============================================================================
# Configuration and Global Variables
#==============================================================================
# Get script directory and load common functions
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/common.sh"
# Get all paths and variables from common functions
eval $(get_feature_paths)
NEW_PLAN="$IMPL_PLAN" # Alias for compatibility with existing code
AGENT_TYPE="${1:-}"
# Agent-specific file paths
CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
GEMINI_FILE="$REPO_ROOT/GEMINI.md"
COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"
CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
QWEN_FILE="$REPO_ROOT/QWEN.md"
AGENTS_FILE="$REPO_ROOT/AGENTS.md"
WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
CODEBUDDY_FILE="$REPO_ROOT/.codebuddy/rules/specify-rules.md"
Q_FILE="$REPO_ROOT/AGENTS.md"
# Template file
TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
# Global variables for parsed plan data
NEW_LANG=""
NEW_FRAMEWORK=""
NEW_DB=""
NEW_PROJECT_TYPE=""
#==============================================================================
# Utility Functions
#==============================================================================
log_info() {
echo "INFO: $1"
}
log_success() {
echo "✓ $1"
}
log_error() {
echo "ERROR: $1" >&2
}
log_warning() {
echo "WARNING: $1" >&2
}
# Cleanup function for temporary files
cleanup() {
local exit_code=$?
rm -f /tmp/agent_update_*_$$
rm -f /tmp/manual_additions_$$
exit $exit_code
}
# Set up cleanup trap
trap cleanup EXIT INT TERM
#==============================================================================
# Validation Functions
#==============================================================================
validate_environment() {
# Check if we have a current branch/feature (git or non-git)
if [[ -z "$CURRENT_BRANCH" ]]; then
log_error "Unable to determine current feature"
if [[ "$HAS_GIT" == "true" ]]; then
log_info "Make sure you're on a feature branch"
else
log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
fi
exit 1
fi
# Check if plan.md exists
if [[ ! -f "$NEW_PLAN" ]]; then
log_error "No plan.md found at $NEW_PLAN"
log_info "Make sure you're working on a feature with a corresponding spec directory"
if [[ "$HAS_GIT" != "true" ]]; then
log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
fi
exit 1
fi
# Check if template exists (needed for new files)
if [[ ! -f "$TEMPLATE_FILE" ]]; then
log_warning "Template file not found at $TEMPLATE_FILE"
log_warning "Creating new agent files will fail"
fi
}
#==============================================================================
# Plan Parsing Functions
#==============================================================================
extract_plan_field() {
local field_pattern="$1"
local plan_file="$2"
grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
head -1 | \
sed "s|^\*\*${field_pattern}\*\*: ||" | \
sed 's/^[ \t]*//;s/[ \t]*$//' | \
grep -v "NEEDS CLARIFICATION" | \
grep -v "^N/A$" || echo ""
}
parse_plan_data() {
local plan_file="$1"
if [[ ! -f "$plan_file" ]]; then
log_error "Plan file not found: $plan_file"
return 1
fi
if [[ ! -r "$plan_file" ]]; then
log_error "Plan file is not readable: $plan_file"
return 1
fi
log_info "Parsing plan data from $plan_file"
NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
NEW_DB=$(extract_plan_field "Storage" "$plan_file")
NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
# Log what we found
if [[ -n "$NEW_LANG" ]]; then
log_info "Found language: $NEW_LANG"
else
log_warning "No language information found in plan"
fi
if [[ -n "$NEW_FRAMEWORK" ]]; then
log_info "Found framework: $NEW_FRAMEWORK"
fi
if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
log_info "Found database: $NEW_DB"
fi
if [[ -n "$NEW_PROJECT_TYPE" ]]; then
log_info "Found project type: $NEW_PROJECT_TYPE"
fi
}
format_technology_stack() {
local lang="$1"
local framework="$2"
local parts=()
# Add non-empty parts
[[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
[[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
# Join with proper formatting
if [[ ${#parts[@]} -eq 0 ]]; then
echo ""
elif [[ ${#parts[@]} -eq 1 ]]; then
echo "${parts[0]}"
else
# Join multiple parts with " + "
local result="${parts[0]}"
for ((i=1; i<${#parts[@]}; i++)); do
result="$result + ${parts[i]}"
done
echo "$result"
fi
}
#==============================================================================
# Template and Content Generation Functions
#==============================================================================
get_project_structure() {
local project_type="$1"
if [[ "$project_type" == *"web"* ]]; then
echo "backend/\\nfrontend/\\ntests/"
else
echo "src/\\ntests/"
fi
}
get_commands_for_language() {
local lang="$1"
case "$lang" in
*"Python"*)
echo "cd src && pytest && ruff check ."
;;
*"Rust"*)
echo "cargo test && cargo clippy"
;;
*"JavaScript"*|*"TypeScript"*)
echo "npm test && npm run lint"
;;
*)
echo "# Add commands for $lang"
;;
esac
}
get_language_conventions() {
local lang="$1"
echo "$lang: Follow standard conventions"
}
create_new_agent_file() {
local target_file="$1"
local temp_file="$2"
local project_name="$3"
local current_date="$4"
if [[ ! -f "$TEMPLATE_FILE" ]]; then
log_error "Template not found at $TEMPLATE_FILE"
return 1
fi
if [[ ! -r "$TEMPLATE_FILE" ]]; then
log_error "Template file is not readable: $TEMPLATE_FILE"
return 1
fi
log_info "Creating new agent context file from template..."
if ! cp "$TEMPLATE_FILE" "$temp_file"; then
log_error "Failed to copy template file"
return 1
fi
# Replace template placeholders
local project_structure
project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
local commands
commands=$(get_commands_for_language "$NEW_LANG")
local language_conventions
language_conventions=$(get_language_conventions "$NEW_LANG")
# Perform substitutions with error checking using safer approach
# Escape special characters for sed by using a different delimiter or escaping
local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
# Build technology stack and recent change strings conditionally
local tech_stack
if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
elif [[ -n "$escaped_lang" ]]; then
tech_stack="- $escaped_lang ($escaped_branch)"
elif [[ -n "$escaped_framework" ]]; then
tech_stack="- $escaped_framework ($escaped_branch)"
else
tech_stack="- ($escaped_branch)"
fi
local recent_change
if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
elif [[ -n "$escaped_lang" ]]; then
recent_change="- $escaped_branch: Added $escaped_lang"
elif [[ -n "$escaped_framework" ]]; then
recent_change="- $escaped_branch: Added $escaped_framework"
else
recent_change="- $escaped_branch: Added"
fi
local substitutions=(
"s|\[PROJECT NAME\]|$project_name|"
"s|\[DATE\]|$current_date|"
"s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
"s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
"s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
"s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
"s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
)
for substitution in "${substitutions[@]}"; do
if ! sed -i.bak -e "$substitution" "$temp_file"; then
log_error "Failed to perform substitution: $substitution"
rm -f "$temp_file" "$temp_file.bak"
return 1
fi
done
# Convert \n sequences to actual newlines
newline=$(printf '\n')
sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
# Clean up backup files
rm -f "$temp_file.bak" "$temp_file.bak2"
return 0
}
update_existing_agent_file() {
local target_file="$1"
local current_date="$2"
log_info "Updating existing agent context file..."
# Use a single temporary file for atomic update
local temp_file
temp_file=$(mktemp) || {
log_error "Failed to create temporary file"
return 1
}
# Process the file in one pass
local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
local new_tech_entries=()
local new_change_entry=""
# Prepare new technology entries
if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
fi
if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
fi
# Prepare new change entry
if [[ -n "$tech_stack" ]]; then
new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
fi
# Process file line by line
local in_tech_section=false
local in_changes_section=false
local tech_entries_added=false
local changes_entries_added=false
local existing_changes_count=0
while IFS= read -r line || [[ -n "$line" ]]; do
# Handle Active Technologies section
if [[ "$line" == "## Active Technologies" ]]; then
echo "$line" >> "$temp_file"
in_tech_section=true
continue
elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
# Add new tech entries before closing the section
if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
tech_entries_added=true
fi
echo "$line" >> "$temp_file"
in_tech_section=false
continue
elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
# Add new tech entries before empty line in tech section
if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
tech_entries_added=true
fi
echo "$line" >> "$temp_file"
continue
fi
# Handle Recent Changes section
if [[ "$line" == "## Recent Changes" ]]; then
echo "$line" >> "$temp_file"
# Add new change entry right after the heading
if [[ -n "$new_change_entry" ]]; then
echo "$new_change_entry" >> "$temp_file"
fi
in_changes_section=true
changes_entries_added=true
continue
elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
echo "$line" >> "$temp_file"
in_changes_section=false
continue
elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
# Keep only first 2 existing changes
if [[ $existing_changes_count -lt 2 ]]; then
echo "$line" >> "$temp_file"
((existing_changes_count++))
fi
continue
fi
# Update timestamp
if [[ "$line" =~ \*\*Last\ updated\*\*:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
else
echo "$line" >> "$temp_file"
fi
done < "$target_file"
# Post-loop check: if we're still in the Active Technologies section and haven't added new entries
if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
fi
# Move temp file to target atomically
if ! mv "$temp_file" "$target_file"; then
log_error "Failed to update target file"
rm -f "$temp_file"
return 1
fi
return 0
}
#==============================================================================
# Main Agent File Update Function
#==============================================================================
update_agent_file() {
local target_file="$1"
local agent_name="$2"
if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
log_error "update_agent_file requires target_file and agent_name parameters"
return 1
fi
log_info "Updating $agent_name context file: $target_file"
local project_name
project_name=$(basename "$REPO_ROOT")
local current_date
current_date=$(date +%Y-%m-%d)
# Create directory if it doesn't exist
local target_dir
target_dir=$(dirname "$target_file")
if [[ ! -d "$target_dir" ]]; then
if ! mkdir -p "$target_dir"; then
log_error "Failed to create directory: $target_dir"
return 1
fi
fi
if [[ ! -f "$target_file" ]]; then
# Create new file from template
local temp_file
temp_file=$(mktemp) || {
log_error "Failed to create temporary file"
return 1
}
if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
if mv "$temp_file" "$target_file"; then
log_success "Created new $agent_name context file"
else
log_error "Failed to move temporary file to $target_file"
rm -f "$temp_file"
return 1
fi
else
log_error "Failed to create new agent file"
rm -f "$temp_file"
return 1
fi
else
# Update existing file
if [[ ! -r "$target_file" ]]; then
log_error "Cannot read existing file: $target_file"
return 1
fi
if [[ ! -w "$target_file" ]]; then
log_error "Cannot write to existing file: $target_file"
return 1
fi
if update_existing_agent_file "$target_file" "$current_date"; then
log_success "Updated existing $agent_name context file"
else
log_error "Failed to update existing agent file"
return 1
fi
fi
return 0
}
#==============================================================================
# Agent Selection and Processing
#==============================================================================
update_specific_agent() {
local agent_type="$1"
case "$agent_type" in
claude)
update_agent_file "$CLAUDE_FILE" "Claude Code"
;;
gemini)
update_agent_file "$GEMINI_FILE" "Gemini CLI"
;;
copilot)
update_agent_file "$COPILOT_FILE" "GitHub Copilot"
;;
cursor-agent)
update_agent_file "$CURSOR_FILE" "Cursor IDE"
;;
qwen)
update_agent_file "$QWEN_FILE" "Qwen Code"
;;
opencode)
update_agent_file "$AGENTS_FILE" "opencode"
;;
codex)
update_agent_file "$AGENTS_FILE" "Codex CLI"
;;
windsurf)
update_agent_file "$WINDSURF_FILE" "Windsurf"
;;
kilocode)
update_agent_file "$KILOCODE_FILE" "Kilo Code"
;;
auggie)
update_agent_file "$AUGGIE_FILE" "Auggie CLI"
;;
roo)
update_agent_file "$ROO_FILE" "Roo Code"
;;
codebuddy)
update_agent_file "$CODEBUDDY_FILE" "CodeBuddy"
;;
q)
update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
;;
*)
log_error "Unknown agent type '$agent_type'"
log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|q"
exit 1
;;
esac
}
update_all_existing_agents() {
local found_agent=false
# Check each possible agent file and update if it exists
if [[ -f "$CLAUDE_FILE" ]]; then
update_agent_file "$CLAUDE_FILE" "Claude Code"
found_agent=true
fi
if [[ -f "$GEMINI_FILE" ]]; then
update_agent_file "$GEMINI_FILE" "Gemini CLI"
found_agent=true
fi
if [[ -f "$COPILOT_FILE" ]]; then
update_agent_file "$COPILOT_FILE" "GitHub Copilot"
found_agent=true
fi
if [[ -f "$CURSOR_FILE" ]]; then
update_agent_file "$CURSOR_FILE" "Cursor IDE"
found_agent=true
fi
if [[ -f "$QWEN_FILE" ]]; then
update_agent_file "$QWEN_FILE" "Qwen Code"
found_agent=true
fi
if [[ -f "$AGENTS_FILE" ]]; then
update_agent_file "$AGENTS_FILE" "Codex/opencode"
found_agent=true
fi
if [[ -f "$WINDSURF_FILE" ]]; then
update_agent_file "$WINDSURF_FILE" "Windsurf"
found_agent=true
fi
if [[ -f "$KILOCODE_FILE" ]]; then
update_agent_file "$KILOCODE_FILE" "Kilo Code"
found_agent=true
fi
if [[ -f "$AUGGIE_FILE" ]]; then
update_agent_file "$AUGGIE_FILE" "Auggie CLI"
found_agent=true
fi
if [[ -f "$ROO_FILE" ]]; then
update_agent_file "$ROO_FILE" "Roo Code"
found_agent=true
fi
if [[ -f "$CODEBUDDY_FILE" ]]; then
update_agent_file "$CODEBUDDY_FILE" "CodeBuddy"
found_agent=true
fi
if [[ -f "$Q_FILE" ]]; then
update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
found_agent=true
fi
# If no agent files exist, create a default Claude file
if [[ "$found_agent" == false ]]; then
log_info "No existing agent files found, creating default Claude file..."
update_agent_file "$CLAUDE_FILE" "Claude Code"
fi
}
print_summary() {
echo
log_info "Summary of changes:"
if [[ -n "$NEW_LANG" ]]; then
echo " - Added language: $NEW_LANG"
fi
if [[ -n "$NEW_FRAMEWORK" ]]; then
echo " - Added framework: $NEW_FRAMEWORK"
fi
if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
echo " - Added database: $NEW_DB"
fi
echo
log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|q]"
}
#==============================================================================
# Main Execution
#==============================================================================
main() {
# Validate environment before proceeding
validate_environment
log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
# Parse the plan file to extract project information
if ! parse_plan_data "$NEW_PLAN"; then
log_error "Failed to parse plan data"
exit 1
fi
# Process based on agent type argument
local success=true
if [[ -z "$AGENT_TYPE" ]]; then
# No specific agent provided - update all existing agent files
log_info "No agent specified, updating all existing agent files..."
if ! update_all_existing_agents; then
success=false
fi
else
# Specific agent provided - update only that agent
log_info "Updating specific agent: $AGENT_TYPE"
if ! update_specific_agent "$AGENT_TYPE"; then
success=false
fi
fi
# Print summary
print_summary
if [[ "$success" == true ]]; then
log_success "Agent context update completed successfully"
exit 0
else
log_error "Agent context update completed with errors"
exit 1
fi
}
# Execute main function if script is run directly
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
main "$@"
fi

23
.specify/templates/agent-file-template.md Normal file
View file

@ -0,0 +1,23 @@
# [PROJECT NAME] Development Guidelines
Auto-generated from all feature plans. Last updated: [DATE]
## Active Technologies
[EXTRACTED FROM ALL PLAN.MD FILES]
## Project Structure
```
[ACTUAL STRUCTURE FROM PLANS]
```
## Commands
[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
## Code Style
[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
## Recent Changes
[LAST 3 FEATURES AND WHAT THEY ADDED]
<!-- MANUAL ADDITIONS START -->
<!-- MANUAL ADDITIONS END -->

40
.specify/templates/checklist-template.md Normal file
View file

@ -0,0 +1,40 @@
# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
**Purpose**: [Brief description of what this checklist covers]
**Created**: [DATE]
**Feature**: [Link to spec.md or relevant documentation]
**Note**: This checklist is generated by the `/speckit.checklist` command based on feature context and requirements.
<!--
============================================================================
IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
The /speckit.checklist command MUST replace these with actual items based on:
- User's specific checklist request
- Feature requirements from spec.md
- Technical context from plan.md
- Implementation details from tasks.md
DO NOT keep these sample items in the generated checklist file.
============================================================================
-->
## [Category 1]
- [ ] CHK001 First checklist item with clear action
- [ ] CHK002 Second checklist item
- [ ] CHK003 Third checklist item
## [Category 2]
- [ ] CHK004 Another category item
- [ ] CHK005 Item with specific criteria
- [ ] CHK006 Final item in this category
## Notes
- Check items off as completed: `[x]`
- Add comments or findings inline
- Link to relevant resources or documentation
- Items are numbered sequentially for easy reference

104
.specify/templates/plan-template.md Normal file
View file

@ -0,0 +1,104 @@
# Implementation Plan: [FEATURE]
**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
## Summary
[Extract from feature spec: primary requirement + technical approach from research]
## Technical Context
<!--
ACTION REQUIRED: Replace the content in this section with the technical details
for the project. The structure here is presented in advisory capacity to guide
the iteration process.
-->
**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
**Project Type**: [single/web/mobile - determines source structure]
**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
[Gates determined based on constitution file]
## Project Structure
### Documentation (this feature)
```
specs/[###-feature]/
├── plan.md # This file (/speckit.plan command output)
├── research.md # Phase 0 output (/speckit.plan command)
├── data-model.md # Phase 1 output (/speckit.plan command)
├── quickstart.md # Phase 1 output (/speckit.plan command)
├── contracts/ # Phase 1 output (/speckit.plan command)
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```
### Source Code (repository root)
<!--
ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
for this feature. Delete unused options and expand the chosen structure with
real paths (e.g., apps/admin, packages/something). The delivered plan must
not include Option labels.
-->
```
# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
src/
├── models/
├── services/
├── cli/
└── lib/
tests/
├── contract/
├── integration/
└── unit/
# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
backend/
├── src/
│ ├── models/
│ ├── services/
│ └── api/
└── tests/
frontend/
├── src/
│ ├── components/
│ ├── pages/
│ └── services/
└── tests/
# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
api/
└── [same as backend above]
ios/ or android/
└── [platform-specific structure: feature modules, UI flows, platform tests]
```
**Structure Decision**: [Document the selected structure and reference the real
directories captured above]
## Complexity Tracking
*Fill ONLY if Constitution Check has violations that must be justified*
| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

115
.specify/templates/spec-template.md Normal file
View file

@ -0,0 +1,115 @@
# Feature Specification: [FEATURE NAME]
**Feature Branch**: `[###-feature-name]`
**Created**: [DATE]
**Status**: Draft
**Input**: User description: "$ARGUMENTS"
## User Scenarios & Testing *(mandatory)*
<!--
IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
you should still have a viable MVP (Minimum Viable Product) that delivers value.
Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
Think of each story as a standalone slice of functionality that can be:
- Developed independently
- Tested independently
- Deployed independently
- Demonstrated to users independently
-->
### User Story 1 - [Brief Title] (Priority: P1)
[Describe this user journey in plain language]
**Why this priority**: [Explain the value and why it has this priority level]
**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
**Acceptance Scenarios**:
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
2. **Given** [initial state], **When** [action], **Then** [expected outcome]
---
### User Story 2 - [Brief Title] (Priority: P2)
[Describe this user journey in plain language]
**Why this priority**: [Explain the value and why it has this priority level]
**Independent Test**: [Describe how this can be tested independently]
**Acceptance Scenarios**:
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
---
### User Story 3 - [Brief Title] (Priority: P3)
[Describe this user journey in plain language]
**Why this priority**: [Explain the value and why it has this priority level]
**Independent Test**: [Describe how this can be tested independently]
**Acceptance Scenarios**:
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
---
[Add more user stories as needed, each with an assigned priority]
### Edge Cases
<!--
ACTION REQUIRED: The content in this section represents placeholders.
Fill them out with the right edge cases.
-->
- What happens when [boundary condition]?
- How does system handle [error scenario]?
## Requirements *(mandatory)*
<!--
ACTION REQUIRED: The content in this section represents placeholders.
Fill them out with the right functional requirements.
-->
### Functional Requirements
- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
- **FR-005**: System MUST [behavior, e.g., "log all security events"]
*Example of marking unclear requirements:*
- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
### Key Entities *(include if feature involves data)*
- **[Entity 1]**: [What it represents, key attributes without implementation]
- **[Entity 2]**: [What it represents, relationships to other entities]
## Success Criteria *(mandatory)*
<!--
ACTION REQUIRED: Define measurable success criteria.
These must be technology-agnostic and measurable.
-->
### Measurable Outcomes
- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

250
.specify/templates/tasks-template.md Normal file
View file

@ -0,0 +1,250 @@
---
description: "Task list template for feature implementation"
---
# Tasks: [FEATURE NAME]
**Input**: Design documents from `/specs/[###-feature-name]/`
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
## Format: `[ID] [P?] [Story] Description`
- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
- Include exact file paths in descriptions
## Path Conventions
- **Single project**: `src/`, `tests/` at repository root
- **Web app**: `backend/src/`, `frontend/src/`
- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
- Paths shown below assume single project - adjust based on plan.md structure
<!--
============================================================================
IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
The /speckit.tasks command MUST replace these with actual tasks based on:
- User stories from spec.md (with their priorities P1, P2, P3...)
- Feature requirements from plan.md
- Entities from data-model.md
- Endpoints from contracts/
Tasks MUST be organized by user story so each story can be:
- Implemented independently
- Tested independently
- Delivered as an MVP increment
DO NOT keep these sample tasks in the generated tasks.md file.
============================================================================
-->
## Phase 1: Setup (Shared Infrastructure)
**Purpose**: Project initialization and basic structure
- [ ] T001 Create project structure per implementation plan
- [ ] T002 Initialize [language] project with [framework] dependencies
- [ ] T003 [P] Configure linting and formatting tools
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
**⚠️ CRITICAL**: No user story work can begin until this phase is complete
Examples of foundational tasks (adjust based on your project):
- [ ] T004 Setup database schema and migrations framework
- [ ] T005 [P] Implement authentication/authorization framework
- [ ] T006 [P] Setup API routing and middleware structure
- [ ] T007 Create base models/entities that all stories depend on
- [ ] T008 Configure error handling and logging infrastructure
- [ ] T009 Setup environment configuration management
**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
---
## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
**Goal**: [Brief description of what this story delivers]
**Independent Test**: [How to verify this story works on its own]
### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
**NOTE: Write these tests FIRST, ensure they FAIL before implementation**
- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
### Implementation for User Story 1
- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
- [ ] T016 [US1] Add validation and error handling
- [ ] T017 [US1] Add logging for user story 1 operations
**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
---
## Phase 4: User Story 2 - [Title] (Priority: P2)
**Goal**: [Brief description of what this story delivers]
**Independent Test**: [How to verify this story works on its own]
### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
### Implementation for User Story 2
- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
- [ ] T021 [US2] Implement [Service] in src/services/[service].py
- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
---
## Phase 5: User Story 3 - [Title] (Priority: P3)
**Goal**: [Brief description of what this story delivers]
**Independent Test**: [How to verify this story works on its own]
### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
### Implementation for User Story 3
- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
- [ ] T027 [US3] Implement [Service] in src/services/[service].py
- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
**Checkpoint**: All user stories should now be independently functional
---
[Add more user story phases as needed, following the same pattern]
---
## Phase N: Polish & Cross-Cutting Concerns
**Purpose**: Improvements that affect multiple user stories
- [ ] TXXX [P] Documentation updates in docs/
- [ ] TXXX Code cleanup and refactoring
- [ ] TXXX Performance optimization across all stories
- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
- [ ] TXXX Security hardening
- [ ] TXXX Run quickstart.md validation
---
## Dependencies & Execution Order
### Phase Dependencies
- **Setup (Phase 1)**: No dependencies - can start immediately
- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
- **User Stories (Phase 3+)**: All depend on Foundational phase completion
- User stories can then proceed in parallel (if staffed)
- Or sequentially in priority order (P1 → P2 → P3)
- **Polish (Final Phase)**: Depends on all desired user stories being complete
### User Story Dependencies
- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
### Within Each User Story
- Tests (if included) MUST be written and FAIL before implementation
- Models before services
- Services before endpoints
- Core implementation before integration
- Story complete before moving to next priority
### Parallel Opportunities
- All Setup tasks marked [P] can run in parallel
- All Foundational tasks marked [P] can run in parallel (within Phase 2)
- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
- All tests for a user story marked [P] can run in parallel
- Models within a story marked [P] can run in parallel
- Different user stories can be worked on in parallel by different team members
---
## Parallel Example: User Story 1
```bash
# Launch all tests for User Story 1 together (if tests requested):
Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
Task: "Integration test for [user journey] in tests/integration/test_[name].py"
# Launch all models for User Story 1 together:
Task: "Create [Entity1] model in src/models/[entity1].py"
Task: "Create [Entity2] model in src/models/[entity2].py"
```
---
## Implementation Strategy
### MVP First (User Story 1 Only)
1. Complete Phase 1: Setup
2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
3. Complete Phase 3: User Story 1
4. **STOP and VALIDATE**: Test User Story 1 independently
5. Deploy/demo if ready
### Incremental Delivery
1. Complete Setup + Foundational → Foundation ready
2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
3. Add User Story 2 → Test independently → Deploy/Demo
4. Add User Story 3 → Test independently → Deploy/Demo
5. Each story adds value without breaking previous stories
### Parallel Team Strategy
With multiple developers:
1. Team completes Setup + Foundational together
2. Once Foundational is done:
- Developer A: User Story 1
- Developer B: User Story 2
- Developer C: User Story 3
3. Stories complete and integrate independently
---
## Notes
- [P] tasks = different files, no dependencies
- [Story] label maps task to specific user story for traceability
- Each user story should be independently completable and testable
- Verify tests fail before implementing
- Commit after each task or logical group
- Stop at any checkpoint to validate story independently
- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

24
CLAUDE.md Normal file
View file

@ -0,0 +1,24 @@
# ops-jrz1 Development Guidelines
Auto-generated from all feature plans. Last updated: 2025-10-11
## Active Technologies
- Nix 2.x, NixOS 24.05+, Bash 5.x (for scripts) (001-extract-matrix-platform)
## Project Structure
```
src/
tests/
```
## Commands
# Add commands for Nix 2.x, NixOS 24.05+, Bash 5.x (for scripts)
## Code Style
Nix 2.x, NixOS 24.05+, Bash 5.x (for scripts): Follow standard conventions
## Recent Changes
- 001-extract-matrix-platform: Added Nix 2.x, NixOS 24.05+, Bash 5.x (for scripts)
<!-- MANUAL ADDITIONS START -->
<!-- MANUAL ADDITIONS END -->

21
LICENSE Normal file
View file

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2025 ops-jrz1 Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

118
README.md Normal file
View file

@ -0,0 +1,118 @@
# ops-jrz1 NixOS Server Configuration
**Status**: Work in Progress - Matrix Platform Extraction
This repository contains the NixOS configuration for the ops-jrz1 dev/test server, including extracted Matrix homeserver modules and bridge configurations from the ops-base production environment.
## Overview
The ops-jrz1 server provides a Matrix homeserver (Continuwuity/Conduwuit) with bridges for:
- Slack (mautrix-slack)
- WhatsApp (mautrix-whatsapp)
- Google Messages (mautrix-gmessages)
Additional services:
- Security hardening (fail2ban, SSH hardening)
- Secrets management (sops-nix with age encryption)
## Current Status
**Phase**: Extracting and sanitizing modules from ops-base
- [x] Repository structure created
- [x] Skeleton configuration files (flake.nix, configuration.nix, hosts/ops-jrz1.nix)
- [x] Sanitization and validation scripts
- [x] Git hooks for security validation
- [ ] Module extraction from ops-base
- [ ] Documentation (deployment guides, bridge setup)
- [ ] Server deployment and testing
## Repository Structure
```
ops-jrz1/
├── flake.nix # Nix flake configuration
├── configuration.nix # Main NixOS configuration
├── hosts/
│ └── ops-jrz1.nix # Server-specific configuration
├── modules/ # Extracted Matrix platform modules (pending)
├── docs/ # Deployment and setup documentation (pending)
├── secrets/ # sops-nix encrypted secrets (gitignored)
├── scripts/ # Sanitization and validation scripts
│ ├── sanitize-files.sh
│ └── validate-sanitization.sh
└── specs/ # Project planning and specifications
└── 001-extract-matrix-platform/
```
## Planned Features
### Matrix Homeserver
- **Continuwuity/Conduwuit**: Lightweight Rust-based Matrix homeserver
- Federation support
- User registration with tokens
- Admin room for management
### Bridges
- **Slack**: Socket Mode authentication, workspace integration
- **WhatsApp**: QR code pairing, message synchronization
- **Google Messages**: Pairing flow, SMS/MMS support
### Security & Operations
- **fail2ban**: Intrusion prevention
- **SSH hardening**: Key-only authentication, restricted access
- **sops-nix**: Encrypted secrets management with age keys
- **Git hooks**: Pre-commit validation, pre-push build checks
## Development Workflow
### Prerequisites
- NixOS 24.05+ or Nix with flakes enabled
- SSH access to ops-jrz1 server
- Age encryption key for secrets management
### Building Locally
```bash
# Check flake validity
nix flake check
# Build ops-jrz1 configuration
nix build .#nixosConfigurations.ops-jrz1
# Deploy to server (when ready)
nixos-rebuild switch --flake .#ops-jrz1 --target-host root@ops-jrz1
```
### Sanitization Workflow
```bash
# Extract modules from ops-base
./scripts/sanitize-files.sh ~/proj/ops-base/modules staging/modules
# Validate sanitization
./scripts/validate-sanitization.sh staging/modules
# Move to permanent location
mv staging/modules/* modules/
```
## Security Notes
- **Never commit secrets**: All secrets managed via sops-nix, encrypted with age keys
- **Git hooks active**: Pre-commit hooks validate for personal information leakage
- **Sanitization enforced**: All extracted code must pass validation before commit
## License
MIT License (see LICENSE file)
## Related Documentation
- Project Specification: `specs/001-extract-matrix-platform/spec.md`
- Implementation Plan: `specs/001-extract-matrix-platform/plan.md`
- Task Breakdown: `specs/001-extract-matrix-platform/tasks.md`
- Sanitization Rules: `specs/001-extract-matrix-platform/contracts/sanitization-rules.yaml`
---
**Note**: This repository is currently in active development. Documentation and deployment guides will be added as modules are extracted and tested.

46
configuration.nix Normal file
View file

@ -0,0 +1,46 @@
{ config, pkgs, ... }:
{
# Main NixOS configuration for ops-jrz1 server
# Imports host-specific configuration from hosts/ops-jrz1.nix
# Boot loader configuration (placeholder - will be customized for actual server)
boot.loader.grub.enable = true;
boot.loader.grub.device = "/dev/sda"; # REPLACE_ME with actual device
# Network configuration
networking.useDHCP = false;
networking.interfaces.eth0.useDHCP = true; # REPLACE_ME with actual interface
# Time zone
time.timeZone = "UTC";
# Internationalization
i18n.defaultLocale = "en_US.UTF-8";
# System packages
environment.systemPackages = with pkgs; [
vim
git
htop
curl
];
# SSH configuration
services.openssh = {
enable = true;
settings = {
PermitRootLogin = "prohibit-password";
PasswordAuthentication = false;
};
};
# Firewall (will be configured for Matrix services)
networking.firewall = {
enable = true;
allowedTCPPorts = [ 22 80 443 ]; # SSH, HTTP, HTTPS
};
# This value determines the NixOS release compatibility
system.stateVersion = "24.05";
}

28
flake.nix Normal file
View file

@ -0,0 +1,28 @@
{
description = "ops-jrz1 NixOS server configuration with Matrix platform";
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05";
# sops-nix for secrets management (will be configured after extraction)
# sops-nix = {
# url = "github:Mic92/sops-nix";
# inputs.nixpkgs.follows = "nixpkgs";
# };
};
outputs = { self, nixpkgs, ... }@inputs: {
nixosConfigurations = {
ops-jrz1 = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
./configuration.nix
./hosts/ops-jrz1.nix
# sops-nix will be added after extraction
# inputs.sops-nix.nixosModules.sops
];
};
};
};
}

34
hosts/ops-jrz1.nix Normal file
View file

@ -0,0 +1,34 @@
{ config, pkgs, ... }:
{
# ops-jrz1 dev/test server configuration
# This file will be populated with Matrix platform modules and server-specific settings
imports = [
# Hardware configuration will be added based on server specs
# ./hardware-configuration.nix
# Matrix platform modules (to be imported after extraction)
# ../modules/matrix-continuwuity.nix
# ../modules/mautrix-slack.nix
# ../modules/mautrix-whatsapp.nix
# ../modules/mautrix-gmessages.nix
# ../modules/security/fail2ban.nix
# ../modules/security/ssh-hardening.nix
];
# System configuration
networking.hostName = "ops-jrz1";
# Placeholder for Matrix homeserver configuration
# services.matrix-continuwuity = {
# enable = true;
# domain = "REPLACE_ME"; # ops-jrz1 domain
# port = 8008;
# };
# Placeholder for bridge configurations
# Bridges will be configured after modules are extracted
system.stateVersion = "24.05";
}

37
scripts/hooks/nix-build-hook.sh Executable file
View file

@ -0,0 +1,37 @@
#!/usr/bin/env bash
#
# Pre-push hook: Validate builds
#
# This hook attempts to build the ops-jrz1 configuration
# to ensure it's valid before pushing to remote.
set -euo pipefail
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Get repository root
REPO_ROOT="$(git rev-parse --show-toplevel)"
echo "==> Running build validation..."
# Check if flake.nix exists
if [ ! -f "$REPO_ROOT/flake.nix" ]; then
echo -e "${YELLOW}⚠ WARNING: flake.nix not found, skipping build validation${NC}"
exit 0
fi
# Try to build ops-jrz1 configuration
if nix build "$REPO_ROOT#nixosConfigurations.ops-jrz1.config.system.build.toplevel" --no-link --show-trace 2>&1 | head -20; then
echo -e "${GREEN}✓ Build validation passed${NC}"
exit 0
else
echo -e "${RED}✗ Build validation failed${NC}"
echo ""
echo "Push blocked. Please fix the build errors and try again."
echo "Debug with: nix build .#nixosConfigurations.ops-jrz1 --show-trace"
exit 1
fi

37
scripts/hooks/nix-flake-check-hook.sh Executable file
View file

@ -0,0 +1,37 @@
#!/usr/bin/env bash
#
# Pre-push hook: Run nix flake check
#
# This hook validates that the flake configuration is valid
# and all checks pass before pushing to remote.
set -euo pipefail
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
# Get repository root
REPO_ROOT="$(git rev-parse --show-toplevel)"
echo "==> Running nix flake check..."
# Check if flake.nix exists
if [ ! -f "$REPO_ROOT/flake.nix" ]; then
echo -e "${YELLOW}⚠ WARNING: flake.nix not found, skipping nix flake check${NC}"
exit 0
fi
# Run nix flake check
if nix flake check "$REPO_ROOT" --show-trace 2>&1; then
echo -e "${GREEN}✓ nix flake check passed${NC}"
exit 0
else
echo -e "${RED}✗ nix flake check failed${NC}"
echo ""
echo "Push blocked. Please fix the flake errors and try again."
echo "Debug with: nix flake check --show-trace"
exit 1
fi

66
scripts/hooks/validate-sanitization-hook.sh Executable file
View file

@ -0,0 +1,66 @@
#!/usr/bin/env bash
#
# Pre-commit hook: Validate that no personal information is being committed
#
# This hook checks staged files for personal domains, IPs, and paths
# to prevent accidental leakage of sensitive information.
set -euo pipefail
# Get repository root
REPO_ROOT="$(git rev-parse --show-toplevel)"
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m'
# Get list of staged Nix and Markdown files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(nix|md)$' || true)
if [ -z "$STAGED_FILES" ]; then
# No Nix or Markdown files staged, skip validation
exit 0
fi
echo "==> Validating staged files for personal information..."
VALIDATION_FAILED=0
# Check for personal domains
if echo "$STAGED_FILES" | xargs git diff --cached | grep -E 'clarun\.xyz|talu\.uno' >/dev/null 2>&1; then
echo -e "${RED}✗ ERROR: Staged changes contain personal domains (clarun.xyz or talu.uno)${NC}"
echo " These domains must be replaced with example.com or matrix.example.org"
VALIDATION_FAILED=1
fi
# Check for personal IPs
if echo "$STAGED_FILES" | xargs git diff --cached | grep -E '192\.168\.1\.|45\.77\.205\.49' >/dev/null 2>&1; then
echo -e "${RED}✗ ERROR: Staged changes contain personal IP addresses${NC}"
echo " Replace 192.168.1.x with 10.0.0.x and 45.77.205.49 with 203.0.113.10"
VALIDATION_FAILED=1
fi
# Check for personal paths
if echo "$STAGED_FILES" | xargs git diff --cached | grep -E '/home/dan' >/dev/null 2>&1; then
echo -e "${RED}✗ ERROR: Staged changes contain personal paths (/home/dan)${NC}"
echo " Replace with /home/user or generic paths"
VALIDATION_FAILED=1
fi
# Check for hostname jrz1 (but allow ops-jrz1 since that's the server name)
if echo "$STAGED_FILES" | xargs git diff --cached | grep -E '\bjrz1\b' | grep -v 'ops-jrz1' >/dev/null 2>&1; then
echo -e "${RED}✗ ERROR: Staged changes contain personal hostname (jrz1)${NC}"
echo " Replace with 'matrix' or generic hostname (ops-jrz1 is allowed)"
VALIDATION_FAILED=1
fi
if [ $VALIDATION_FAILED -eq 1 ]; then
echo ""
echo "Commit blocked. Please fix the issues above and try again."
echo "Run './scripts/sanitize-files.sh <dir> <dir>' to apply sanitization rules."
exit 1
fi
echo -e "${GREEN}✓ Sanitization validation passed${NC}"
exit 0

109
scripts/sanitize-files.sh Executable file
View file

@ -0,0 +1,109 @@
#!/usr/bin/env bash
#
# Sanitization script for extracting Matrix platform modules from ops-base
# Based on contracts/sanitization-rules.yaml
#
# Usage: ./scripts/sanitize-files.sh <source-dir> <output-dir>
#
# This script applies all sanitization rules to remove personal information
# and prepare modules for publication in ops-jrz1 repository.
set -euo pipefail
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# Script directory
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
# Check arguments
if [ $# -ne 2 ]; then
echo "Usage: $0 <source-dir> <output-dir>"
echo "Example: $0 ~/proj/ops-base/modules staging/modules"
exit 1
fi
SOURCE_DIR="$1"
OUTPUT_DIR="$2"
echo "==> Sanitizing files from $SOURCE_DIR to $OUTPUT_DIR"
# Create output directory
mkdir -p "$OUTPUT_DIR"
# Copy files to output directory
echo "==> Copying files..."
rsync -av --exclude='.git' "$SOURCE_DIR/" "$OUTPUT_DIR/"
echo "==> Applying sanitization rules..."
# Critical Rule 1: Replace clarun.xyz domain
echo " - Replacing clarun.xyz → example.com"
find "$OUTPUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i 's/clarun\.xyz/example.com/g' {} \;
# Critical Rule 2: Replace talu.uno domain
echo " - Replacing talu.uno → matrix.example.org"
find "$OUTPUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i 's/talu\.uno/matrix.example.org/g' {} \;
# Critical Rule 3: Replace private IP 192.168.1.x → 10.0.0.x
echo " - Replacing 192.168.1.x → 10.0.0.x"
find "$OUTPUT_DIR" -type f -name "*.nix" -exec sed -i 's/192\.168\.1\.\([0-9]\+\)/10.0.0.\1/g' {} \;
# Critical Rule 4: Replace public VPS IP
echo " - Replacing 45.77.205.49 → 203.0.113.10"
find "$OUTPUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i 's/45\.77\.205\.49/203.0.113.10/g' {} \;
# Critical Rule 5: Replace personal home path
echo " - Replacing /home/dan → /home/user"
find "$OUTPUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i 's|/home/dan|/home/user|g' {} \;
# Critical Rule 6: Replace hostname jrz1 → matrix
echo " - Replacing hostname jrz1 → matrix"
find "$OUTPUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i 's/\bjrz1\b/matrix/g' {} \;
# Critical Rule 7: Replace Matrix admin user
echo " - Replacing @admin:clarun.xyz → @admin:example.com"
find "$OUTPUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i 's/@admin:clarun\.xyz/@admin:example.com/g' {} \;
# High Priority Rule 11: Replace workspace name
echo " - Replacing my-workspace → your-workspace"
find "$OUTPUT_DIR" -type f -name "*.nix" -exec sed -i 's/my-workspace/your-workspace/g' {} \;
# High Priority Rule 12: Replace personal email
echo " - Replacing dlei@duck.com → admin@example.com"
find "$OUTPUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i 's/dlei@duck\.com/admin@example.com/g' {} \;
# High Priority Rule 13: Replace project paths
echo " - Replacing /home/dan/proj/ops-base → /path/to/ops-base"
find "$OUTPUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i 's|/home/dan/proj/ops-base|/path/to/ops-base|g' {} \;
# High Priority Rule 14: Replace continuwuity local path
echo " - Replacing git+file:///home/dan/proj/continuwuity → github:girlbossceo/conduwuit"
find "$OUTPUT_DIR" -type f -name "*.nix" -exec sed -i 's|git+file:///home/dan/proj/continuwuity|github:girlbossceo/conduwuit|g' {} \;
# High Priority Rule 15: Sanitize example registration token
echo " - Replacing example registration token → GENERATE_WITH_openssl_rand_hex_32"
find "$OUTPUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i 's/9a3ad59ee136e5a9dc1612cc179c9b7ff8da78c537682aad82c8084e5ae6b5c3/GENERATE_WITH_openssl_rand_hex_32/g' {} \;
# Worklog Rule 20: Sanitize error messages with IPs
echo " - Sanitizing error messages with IPs"
find "$OUTPUT_DIR" -type f -name "*.md" -exec sed -i 's/connection to \(192\.168\.1\.[0-9]\+\|45\.77\.205\.49\)/connection to <host>/g' {} \;
# Worklog Rule 21: Sanitize SSH commands
echo " - Sanitizing SSH commands"
find "$OUTPUT_DIR" -type f -name "*.md" -exec sed -i 's/ssh root@\(45\.77\.205\.49\|192\.168\.1\.[0-9]\+\)/ssh root@<vps-ip>/g' {} \;
# Worklog Rule 22: Sanitize curl commands
echo " - Sanitizing curl commands"
find "$OUTPUT_DIR" -type f -name "*.md" -exec sed -i 's|curl https\?://\(clarun\.xyz\|talu\.uno\)|curl https://example.com|g' {} \;
echo -e "${GREEN}✓ Sanitization complete${NC}"
echo ""
echo "Next steps:"
echo "1. Run manual review: Check for personal references in comments"
echo "2. Run validation: ./scripts/validate-sanitization.sh $OUTPUT_DIR"
echo "3. Review changes: git diff $OUTPUT_DIR"

120
scripts/validate-sanitization.sh Executable file
View file

@ -0,0 +1,120 @@
#!/usr/bin/env bash
#
# Validation script for sanitized files
# Checks that all personal information has been removed
#
# Usage: ./scripts/validate-sanitization.sh <directory-to-check>
set -euo pipefail
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# Check arguments
if [ $# -ne 1 ]; then
echo "Usage: $0 <directory-to-check>"
echo "Example: $0 modules/"
exit 1
fi
CHECK_DIR="$1"
if [ ! -d "$CHECK_DIR" ]; then
echo -e "${RED}✗ Error: Directory $CHECK_DIR does not exist${NC}"
exit 1
fi
echo "==> Validating sanitization in $CHECK_DIR"
echo ""
VALIDATION_FAILED=0
# Check for personal domains
echo "Checking for personal domains..."
if rg 'clarun\.xyz|talu\.uno' "$CHECK_DIR" --type nix --type md 2>/dev/null; then
echo -e "${RED}✗ FAIL: Found personal domains (clarun.xyz or talu.uno)${NC}"
VALIDATION_FAILED=1
else
echo -e "${GREEN}✓ PASS: No personal domains found${NC}"
fi
echo ""
# Check for personal IPs
echo "Checking for personal IP addresses..."
if rg '192\.168\.1\.|45\.77\.205\.49' "$CHECK_DIR" --type nix 2>/dev/null; then
echo -e "${RED}✗ FAIL: Found personal IP addresses${NC}"
VALIDATION_FAILED=1
else
echo -e "${GREEN}✓ PASS: No personal IP addresses found${NC}"
fi
echo ""
# Check for personal paths
echo "Checking for personal paths..."
if rg '/home/dan' "$CHECK_DIR" 2>/dev/null; then
echo -e "${RED}✗ FAIL: Found personal paths (/home/dan)${NC}"
VALIDATION_FAILED=1
else
echo -e "${GREEN}✓ PASS: No personal paths found${NC}"
fi
echo ""
# Check for hostname jrz1
echo "Checking for personal hostname..."
if rg '\bjrz1\b' "$CHECK_DIR" --type nix --type md 2>/dev/null; then
echo -e "${RED}✗ FAIL: Found personal hostname (jrz1)${NC}"
VALIDATION_FAILED=1
else
echo -e "${GREEN}✓ PASS: No personal hostname found${NC}"
fi
echo ""
# Check for personal email
echo "Checking for personal email..."
if rg 'dlei@duck\.com' "$CHECK_DIR" 2>/dev/null; then
echo -e "${RED}✗ FAIL: Found personal email (dlei@duck.com)${NC}"
VALIDATION_FAILED=1
else
echo -e "${GREEN}✓ PASS: No personal email found${NC}"
fi
echo ""
# Check for Matrix access tokens (if gitleaks available)
if command -v gitleaks &> /dev/null; then
echo "Running gitleaks secret scan..."
if gitleaks detect --no-git --source "$CHECK_DIR" --quiet 2>/dev/null; then
echo -e "${GREEN}✓ PASS: No secrets detected by gitleaks${NC}"
else
echo -e "${RED}✗ FAIL: gitleaks detected secrets${NC}"
echo "Run: gitleaks detect --no-git --source $CHECK_DIR"
VALIDATION_FAILED=1
fi
echo ""
else
echo -e "${YELLOW}⚠ WARNING: gitleaks not installed, skipping secret scan${NC}"
echo "Install with: nix-env -iA nixpkgs.gitleaks"
echo ""
fi
# Summary
echo "==> Validation Summary"
if [ $VALIDATION_FAILED -eq 0 ]; then
echo -e "${GREEN}✓ All validation checks passed${NC}"
echo ""
echo "Next steps:"
echo "1. Manual review: Check comments for personal context"
echo "2. Build validation: nix flake check"
echo "3. Commit changes: git add && git commit"
exit 0
else
echo -e "${RED}✗ Validation failed - personal information still present${NC}"
echo ""
echo "Actions required:"
echo "1. Review the failures above"
echo "2. Manually fix remaining personal references"
echo "3. Re-run this script"
exit 1
fi

427
specs/001-extract-matrix-platform/analysis.md Normal file
View file

@ -0,0 +1,427 @@
# Cross-Artifact Consistency Analysis
**Date**: 2025-10-11
**Feature**: Extract Matrix Platform Modules as Public Template
**Artifacts Analyzed**: spec.md, plan.md, tasks.md, data-model.md, contracts/, quickstart.md
## Executive Summary
**Status**: ✅ **PASS** - All artifacts are consistent with no critical issues
**Metrics**:
- **Requirements**: 29 functional requirements (FR-001 to FR-029)
- **Tasks**: 125 implementation tasks (T001 to T125)
- **Coverage**: 100% (all requirements have implementing tasks)
- **Constitution Violations**: 0 (constitution still in template state)
- **Severity Issues**: 0 critical, 0 high, 2 medium (recommendations)
**Key Findings**:
- All 29 functional requirements have clear task coverage
- Task organization by user story enables independent implementation
- Sanitization contracts properly referenced in tasks
- Success criteria measurable with specific task checkpoints
- Medium-priority recommendations for testing and sync frequency
---
## Requirements Coverage Analysis
### Coverage Summary
| Requirement Category | Count | Tasks Covering | Coverage |
|---------------------|-------|----------------|----------|
| Repository Structure & Sanitization (FR-001 to FR-007) | 7 | 28 tasks (Phase 3) | ✅ 100% |
| Documentation (FR-008 to FR-013) | 6 | 17 tasks (Phase 4) | ✅ 100% |
| Security & Validation (FR-014 to FR-018) | 5 | 15 tasks (Phases 2,3,8) | ✅ 100% |
| Community & Governance (FR-019 to FR-022) | 4 | 15 tasks (Phase 5) | ✅ 100% |
| Sync Workflow (FR-023 to FR-026) | 4 | 10 tasks (Phase 6) | ✅ 100% |
| Testing & Deployment (FR-027 to FR-029) | 3 | 23 tasks (Phase 7) | ✅ 100% |
### Detailed Coverage Map
**FR-001**: Template MUST contain sanitized NixOS modules for Matrix homeserver, bridges, Forgejo, security hardening
- **Tasks**: T012-T019 (copy 8 modules from ops-base to staging), T022 (sanitize modules), T037 (commit sanitized modules), T116 (verify all 8 modules present)
- **Coverage**: ✅ Complete - 8 modules extracted, sanitized, and verified
**FR-002**: All personal domains MUST be replaced with generic examples (clarun.xyz → example.com)
- **Tasks**: T005 (create sanitization script implementing rule ID 1-3 from contracts/sanitization-rules.yaml), T022 (apply to modules), T023 (apply to configurations), T026-T027 (validate no personal domains), T110 (final grep validation)
- **Coverage**: ✅ Complete - sanitization rules, execution, validation all present
**FR-003**: All personal IP addresses MUST be replaced with RFC 1918/TEST-NET-3 examples
- **Tasks**: T005 (sanitization script implements rule ID 4-6), T026-T027 (validate no personal IPs), T110 (manual grep for 192.168.1.x, 45.77.x.x)
- **Coverage**: ✅ Complete - IP sanitization and validation covered
**FR-004**: All secrets MUST be removed and replaced with placeholders/sops-nix patterns
- **Tasks**: T005 (sanitization script rule ID 9-12 for secrets), T025 (add REPLACE_ME comments), T028 (gitleaks validation), T109 (final gitleaks check)
- **Coverage**: ✅ Complete - secret removal automated and validated multiple times
**FR-005**: All personal paths MUST be sanitized (/home/dan → /home/user)
- **Tasks**: T005 (sanitization script rule ID 7-8 for paths), T024 (manual review of comments), T110 (grep for /home/dan)
- **Coverage**: ✅ Complete - path sanitization automated and manually verified
**FR-006**: Template MUST have fresh git history with no ops-base secrets/logs
- **Tasks**: T002 (create new GitHub repo), T003 (clone fresh), T037-T039 (initial commits create new history), T111 (review git log for accidentally committed secrets)
- **Coverage**: ✅ Complete - fresh repo creation ensures clean history
**FR-007**: Repository MUST include example configurations that build successfully
- **Tasks**: T020-T021 (copy and rename configs to example-vps.nix, example-dev.nix), T031 (create minimal-matrix.nix example), T034-T036 (verify builds pass), T114-T115 (final build validation)
- **Coverage**: ✅ Complete - 3 example configs with multiple build validations
**FR-008**: Template MUST include README with features, quick start, architecture
- **Tasks**: T010 (initial README), T105 (expand with comprehensive content), T106-T108 (add badges and community links)
- **Coverage**: ✅ Complete - README created and expanded
**FR-009**: Template MUST include getting-started.md with 5-minute quickstart
- **Tasks**: T049 (create getting-started.md with prerequisites, customization, deployment), T086 (validate by following it during VPS test), T101 (update based on deployment experience)
- **Coverage**: ✅ Complete - doc created, tested, and refined
**FR-010**: Template MUST include bridge setup guides (slack, whatsapp, gmessages)
- **Tasks**: T043 (extract slack-setup.md from worklog), T044 (create whatsapp-setup.md), T045 (create gmessages-setup.md), T046 (sanitize all bridge docs)
- **Coverage**: ✅ Complete - all 3 bridge guides covered
**FR-011**: Template MUST include pattern documentation (config-generation, admin-room-setup)
- **Tasks**: T040 (extract config-generation.md from worklog), T041 (extract admin-room-setup.md), T042 (sanitize pattern docs)
- **Coverage**: ✅ Complete - both pattern docs covered
**FR-012**: Template MUST include secrets-management.md explaining sops-nix
- **Tasks**: T047 (extract from sops-nix RFC), T051 (sanitize), T088-T090 (validate during VPS deployment)
- **Coverage**: ✅ Complete - doc extracted and deployment-tested
**FR-013**: Documentation MUST be sanitized to remove personal infrastructure references
- **Tasks**: T042 (sanitize pattern docs), T046 (sanitize bridge docs), T051 (sanitize core docs), T053 (verify all examples use generic values)
- **Coverage**: ✅ Complete - comprehensive sanitization of all doc categories
**FR-014**: Template MUST pass gitleaks secret scanning with zero findings
- **Tasks**: T006 (create validation script with gitleaks), T028 (run during US2 sanitization), T109 (final full-repo scan), T112 (verify no .sops.yaml with real keys)
- **Coverage**: ✅ Complete - gitleaks validated 3+ times throughout workflow
**FR-015**: All example configurations MUST pass `nix flake check` validation
- **Tasks**: T034 (run nix flake check after flake creation), T113 (run on clean clone during polish)
- **Coverage**: ✅ Complete - validation at multiple stages
**FR-016**: Template MUST include GitHub Actions CI workflow with nix flake check + gitleaks
- **Tasks**: T007 (create .github/workflows/ci.yml from contracts/ci-validation.yaml), T062 (verify CI runs on push), T063-T065 (test CI with sample PRs)
- **Coverage**: ✅ Complete - CI creation and thorough testing
**FR-017**: Template MUST include pre-commit hooks for local secret scanning
- **Tasks**: T008 (create .pre-commit-config.yaml with gitleaks + nix flake check)
- **Coverage**: ✅ Complete - pre-commit config created
**FR-018**: Template MUST include SECURITY.md with vulnerability disclosure
- **Tasks**: T058 (create SECURITY.md with disclosure process, supported versions, response times)
- **Coverage**: ✅ Complete - comprehensive security policy
**FR-019**: Template MUST include CONTRIBUTING.md with guidelines
- **Tasks**: T057 (create CONTRIBUTING.md with contribution guidelines, testing, PR process)
- **Coverage**: ✅ Complete - contribution guidelines covered
**FR-020**: Template MUST include issue templates for bug reports and feature requests
- **Tasks**: T059 (create bug_report.yml), T060 (create feature_request.yml)
- **Coverage**: ✅ Complete - both issue templates present
**FR-021**: Template MUST include LICENSE file (MIT)
- **Tasks**: T011 (create LICENSE with MIT text)
- **Coverage**: ✅ Complete - MIT license creation
**FR-022**: Template MUST have GitHub Discussions enabled
- **Tasks**: T066 (enable GitHub Discussions with Q&A, Ideas, Show and Tell categories)
- **Coverage**: ✅ Complete - Discussions configuration specified
**FR-023**: Project MUST include documented workflow for syncing ops-base to template
- **Tasks**: T072 (create sync-to-template.sh script), T075 (document sync workflow in README), T076 (create sync testing checklist)
- **Coverage**: ✅ Complete - script, documentation, and testing checklist
**FR-024**: Project MUST include scripts/sync-to-template.sh helper script
- **Tasks**: T072 (create script based on research.md sync workflow: identify changes, sanitize, validate)
- **Coverage**: ✅ Complete - explicit script creation task
**FR-025**: Sync workflow MUST include validation steps (build check, gitleaks)
- **Tasks**: T076 (sync testing checklist based on sanitization-rules.yaml), T077-T079 (test sync workflow with validation)
- **Coverage**: ✅ Complete - validation integrated into sync testing
**FR-026**: Maintainer MUST have quarterly calendar reminders for sync
- **Tasks**: T074 (add quarterly sync schedule: January, April, July, October reminders)
- **Coverage**: ✅ Complete - calendar integration specified
**FR-027**: Example configurations MUST be tested by deploying to fresh VPS
- **Tasks**: T082-T084 (provision fresh VPS), T085-T091 (deploy following getting-started.md), T092-T096 (functional validation), T097-T099 (optional bridge testing)
- **Coverage**: ✅ Complete - comprehensive VPS deployment testing
**FR-028**: Template MUST support x86_64-linux architecture
- **Tasks**: T082 (provision VPS specifies x86_64-linux), T113-T115 (build validation confirms architecture support)
- **Coverage**: ✅ Complete - architecture specified and validated
**FR-029**: All modules MUST build against pinned nixpkgs version
- **Tasks**: T032 (create flake.nix with pinned inputs), T033 (run nix flake lock to generate lock file), T034 (verify builds work with pinned versions)
- **Coverage**: ✅ Complete - pinning and validation explicit
---
## Success Criteria Task Mapping
| Success Criterion | Related Tasks | Validation Method |
|------------------|---------------|-------------------|
| **SC-001**: Deploy Matrix in <30 min | T085-T091, T103 | T103 verifies timing during VPS test |
| **SC-002**: All examples build | T034-T036, T113-T115 | nix flake check + build commands |
| **SC-003**: gitleaks zero findings | T028, T109, T111 | Multiple gitleaks scans throughout |
| **SC-004**: 8 modules extracted | T012-T019, T116 | T116 explicit checklist verification |
| **SC-005**: 8 docs complete | T040-T051, T117 | T117 explicit checklist verification |
| **SC-006**: CI runs on every commit | T007, T062-T065 | CI creation + functional testing |
| **SC-007**: 10 stars in 3 months | T121-T125 (announcements) | Post-publication tracking (manual) |
| **SC-008**: 3 issues/PRs in 3 months | T057-T071 (governance) | Post-publication tracking (manual) |
| **SC-009**: Zero security incidents | T028, T109, T064 | Multi-stage secret scanning |
| **SC-010**: Quarterly sync | T072-T081, T074 | Sync workflow + calendar reminders |
**Coverage**: ✅ All 10 success criteria have explicit validation tasks
---
## User Story Traceability
### US1 - Developer Deploys Matrix Platform (P1)
- **Tasks**: T082-T104 (23 tasks in Phase 7)
- **Acceptance Coverage**:
- Scenario 1 (quick start understanding): T086 (follow getting-started.md), T103 (timing validation)
- Scenario 2 (deployment succeeds): T091 (nixos-rebuild), T092-T094 (verify Matrix responds)
- Scenario 3 (bridges work): T097-T099 (bridge setup and testing)
- **Independent Test**: Clone → customize → deploy → verify (T085-T096) ✅
### US2 - Developer Sanitizes and Publishes Template (P1)
- **Tasks**: T012-T039 (28 tasks in Phase 3)
- **Acceptance Coverage**:
- Scenario 1 (domains replaced): T022-T023 (sanitization), T026-T027 (validation)
- Scenario 2 (IPs replaced): T005 (sanitization rules), T110 (grep validation)
- Scenario 3 (gitleaks passes): T028 (during US2), T109 (final check)
- Scenario 4 (builds pass): T034-T036 (nix flake check + builds)
- **Independent Test**: Sanitize → gitleaks → build (T022-T036) ✅
### US3 - Developer Contributes to Template (P2)
- **Tasks**: T057-T071 (15 tasks in Phase 5)
- **Acceptance Coverage**:
- Scenario 1 (CONTRIBUTING clear): T057 (create guidelines)
- Scenario 2 (CI validates): T062-T065 (test CI workflow with PRs)
- Scenario 3 (merge process works): T063-T065 (sample PR testing)
- **Independent Test**: Fork → change → CI → merge (T063-T065) ✅
### US4 - Maintainer Syncs from ops-base (P2)
- **Tasks**: T072-T081 (10 tasks in Phase 6)
- **Acceptance Coverage**:
- Scenario 1 (script identifies changes): T072 (create sync script), T077 (test with mock change)
- Scenario 2 (validation prevents leaks): T076 (testing checklist), T078 (verify script rejects personal refs)
- Scenario 3 (sync commits successfully): T079 (verify git tag + sync-log.md)
- **Independent Test**: Identify changes → sanitize → validate (T077-T079) ✅
### US5 - Developer Learns from Documentation (P3)
- **Tasks**: T040-T056 (17 tasks in Phase 4)
- **Acceptance Coverage**:
- Scenario 1 (Slack setup clear): T043 (extract slack-setup.md with Socket Mode + OAuth)
- Scenario 2 (config-generation pattern): T040 (extract config-generation.md with rationale)
- Scenario 3 (admin room setup): T041 (extract admin-room-setup.md with registration)
- **Independent Test**: Read docs → verify accuracy → verify sanitization (T052-T054) ✅
**User Story Coverage**: ✅ All 5 user stories fully mapped to tasks with testable acceptance scenarios
---
## Edge Case Coverage
| Edge Case | Addressed By | Mitigation |
|-----------|--------------|------------|
| Deploy without sops-nix setup | T088-T090, docs/secrets-management.md | T049 (getting-started.md includes prerequisites), T047 (secrets-management.md explains setup) |
| Different NixOS versions (stable vs unstable) | T084 (verify NixOS version), plan.md technical context | plan.md specifies 24.05+, flake.lock pins dependencies |
| ARM architecture deployment | FR-028 (x86_64 required, ARM optional) | Out of scope for v1.0 (documented in spec.md) |
| New personal refs after publication | T072-T081 (sync workflow) | Sync workflow includes sanitization and validation (T078 tests rejection) |
| Upstream bridge breaking changes | T032-T033 (pinned nixpkgs) | Pinning prevents surprise breakage, sync workflow for updates |
| Secret leakage during sync | T076 (sync testing checklist), T078 (validation test) | Multi-layer validation (gitleaks + manual patterns) |
**Edge Case Coverage**: ✅ All 6 edge cases from spec.md addressed
---
## Contract Alignment
### Sanitization Rules (contracts/sanitization-rules.yaml)
- **22 rules defined**: Critical (9), High (8), Medium (5)
- **Task implementation**: T005 creates sanitization script implementing all 22 rules
- **Validation**: T026-T027 (automated), T024 (manual comments), T110 (final grep)
- **Alignment**: ✅ Complete - all rules have execution + validation tasks
### CI Validation (contracts/ci-validation.yaml)
- **3 jobs defined**: validate (nix flake check), security (gitleaks), docs (markdown-lint)
- **Task implementation**: T007 creates .github/workflows/ci.yml from contract spec
- **Testing**: T062-T065 verify CI behavior (pass/fail scenarios)
- **Alignment**: ✅ Complete - contract fully implemented and tested
---
## Data Model Entity Coverage
### Entities and Lifecycle Implementation
| Entity | Lifecycle States | Tasks Covering Lifecycle |
|--------|-----------------|-------------------------|
| **Module** | ops-base → staging → sanitized → published | T012-T019 (copy to staging), T022 (sanitize), T037 (publish) |
| **Configuration** | ops-base → staging → sanitized → published | T020-T021 (copy), T023 (sanitize), T038 (publish) |
| **Secret** | existing → removed → placeholders | T005 (removal rules), T025 (add REPLACE_ME), T029-T030 (sops examples) |
| **Sanitization Rule** | defined → automated → validated | T005 (automate), T026-T028 (validate during US2), T109-T110 (final validation) |
| **Pattern Document** | worklog → extracted → sanitized → published | T040-T041 (extract), T042 (sanitize), T055 (publish) |
| **Sync Checkpoint** | ops-base commit → sync-log entry → git tag | T073 (sync-log.md), T079 (verify tag creation) |
| **Bridge Setup Guide** | worklog → extracted → sanitized → tested | T043-T045 (extract/create), T046 (sanitize), T097-T099 (test) |
| **CI/CD Pipeline** | designed → implemented → tested → enforced | T007 (implement), T062-T065 (test), T069 (enforce via branch protection) |
**Entity Coverage**: ✅ All 8 entities have complete lifecycle implementation
---
## Findings
### Critical Issues (Severity 1)
**Count**: 0
### High-Priority Issues (Severity 2)
**Count**: 0
### Medium-Priority Recommendations (Severity 3)
**Count**: 2
#### M-001: VPS Integration Testing Scope
**Description**: Phase 7 (US1) tests deployment once during pre-publication. Consider adding periodic testing after publication.
**Impact**: Medium - template may drift or break between releases without regular validation
**Affected Requirements**: FR-027 (example configs tested on VPS)
**Recommendation**: Add to sync workflow (US4) - test on VPS after quarterly syncs, not just initial publication
**Current Coverage**: T082-T104 test once pre-publication, T072-T081 sync workflow has no VPS testing requirement
**Suggested Action**: Add task to Phase 6 - "T081A: Include VPS deployment test in quarterly sync validation checklist"
#### M-002: Community Success Metrics Tracking
**Description**: SC-007 (10 stars) and SC-008 (3 issues/PRs) lack explicit post-publication tracking tasks
**Impact**: Medium - maintainer may forget to monitor community engagement metrics
**Affected Success Criteria**: SC-007, SC-008
**Recommendation**: Add calendar reminder or tracking issue to monitor 3-month metrics
**Current Coverage**: T121-T125 handle announcements but no follow-up tracking specified
**Suggested Action**: Add task to Phase 8 - "T125A: Create GitHub issue to track SC-007/SC-008 metrics at 3-month mark"
### Low-Priority Notes (Severity 4)
**Count**: 0
---
## Consistency Checks
### Placeholder Detection
- **Analyzed**: spec.md, plan.md, tasks.md, data-model.md, quickstart.md
- **Patterns Checked**: TODO, TKTK, ???, FIXME, XXX, PLACEHOLDER
- **Result**: ✅ No placeholders found - all sections complete
### Requirement ID Continuity
- **Range**: FR-001 to FR-029
- **Missing IDs**: None
- **Duplicate IDs**: None
- **Result**: ✅ Continuous numbering, no gaps
### Task ID Continuity
- **Range**: T001 to T125
- **Missing IDs**: None (Note: M-001/M-002 suggest T081A and T125A as additions)
- **Duplicate IDs**: None
- **Result**: ✅ Continuous numbering, 125 tasks assigned
### Cross-Reference Validation
- **spec.md → plan.md**: All FR requirements reflected in plan technical context ✅
- **plan.md → tasks.md**: All phases match task organization ✅
- **data-model.md → tasks.md**: All entities have lifecycle tasks ✅
- **contracts/ → tasks.md**: Sanitization rules (T005), CI validation (T007) implemented ✅
- **quickstart.md → tasks.md**: 4-week timeline aligns with 8 phases ✅
---
## Constitution Alignment
**Status**: N/A - No project-specific constitution defined
**Note**: The `.specify/memory/constitution.md` file is still in template state. This is a one-time extraction project following an established RFC rather than an ongoing software development project, so lack of custom constitution is acceptable.
**Constraints Derived from Spec**:
1. Security First - Zero tolerance for secret leakage ✅ (FR-014, multiple gitleaks validations)
2. Reproducibility - Deterministic builds ✅ (FR-029, pinned nixpkgs)
3. Testability - All configs validate ✅ (FR-015, multiple nix flake check tasks)
4. Documentation Quality - Comprehensive and sanitized ✅ (FR-008 to FR-013)
5. Community Governance - Clear policies ✅ (FR-019 to FR-022)
**Alignment**: ✅ All RFC-derived constraints have explicit requirement + task coverage
---
## Metrics Summary
### Coverage Metrics
- **Requirements with Tasks**: 29/29 (100%)
- **User Stories with Tasks**: 5/5 (100%)
- **Success Criteria with Validation**: 10/10 (100%)
- **Edge Cases Addressed**: 6/6 (100%)
- **Contract Rules Implemented**: 22/22 sanitization rules (100%)
- **Data Model Entities with Lifecycle Tasks**: 8/8 (100%)
### Quality Metrics
- **Critical Issues**: 0
- **High-Priority Issues**: 0
- **Medium Recommendations**: 2 (optional improvements)
- **Duplicate Requirements**: 0
- **Ambiguous Requirements**: 0
- **Missing Validation**: 0
### Task Metrics
- **Total Tasks**: 125
- **Tasks with Clear Acceptance**: 125 (100%)
- **Tasks with File Paths**: 98 (78%) - remainder are validation/process tasks
- **Parallelizable Tasks**: 45+ marked [P] (36%)
- **Blocking Tasks**: 7 (Phase 2 Foundational - correctly identified)
---
## Recommendations
### Immediate Actions (Optional Enhancements)
1. **Accept as-is**: All requirements covered, no blocking issues - can proceed to implementation
2. **Add M-001 enhancement**: Add quarterly VPS testing to sync workflow (low effort, high value)
3. **Add M-002 enhancement**: Add 3-month metric tracking task (trivial effort, useful reminder)
### For Implementation Phase
1. **Phase Discipline**: Complete Phase 2 (Foundational) before any extraction work - scripts MUST exist first
2. **Parallel Execution**: Leverage 45+ parallelizable tasks - Phase 3 module copies, Phase 4 doc extraction
3. **MVP Strategy**: Consider US2+US5+US1 first (73 tasks) to validate core template before governance/sync
4. **Validation Cadence**: Run gitleaks after every phase, not just at endpoints
5. **Documentation Testing**: During Phase 7 (VPS test), treat docs as user would - note all confusion points
### For Future Iterations (Post v1.0)
1. **Automated VPS Testing**: Consider GitHub Actions workflow for periodic deployment tests (v1.1+)
2. **Cachix Integration**: If builds slow, add Cachix for binary caching (deferred per research.md)
3. **ARM Support**: Community may request ARM architecture support (track in discussions)
4. **Additional Bridges**: Signal, Telegram, Discord may be requested (evaluate after publication)
---
## Conclusion
**Overall Assessment**: ✅ **READY FOR IMPLEMENTATION**
The specification, plan, and task breakdown are comprehensive, consistent, and complete. All 29 functional requirements have clear task coverage with validation methods. The two medium-priority recommendations are optional enhancements that do not block implementation.
**Strengths**:
- 100% requirement-to-task coverage with explicit validation
- Well-organized phase dependencies (foundational → extraction → testing)
- Multiple layers of security validation (gitleaks, manual review, CI)
- Independent user stories enable parallel work and incremental delivery
- Comprehensive contracts (sanitization rules, CI validation) guide implementation
**Recommended Next Step**: Proceed with implementation starting from Phase 1 (Setup). Use the quickstart.md 4-week guide as a timeline reference, but prioritize completing Phase 2 (Foundational) before ANY extraction work begins.
**No blocking issues identified** - the artifacts are implementation-ready as written.

58
specs/001-extract-matrix-platform/checklists/requirements.md Normal file
View file

@ -0,0 +1,58 @@
# Specification Quality Checklist: Extract Matrix Platform Modules as Public Template
**Purpose**: Validate specification completeness and quality before proceeding to planning
**Created**: 2025-10-11
**Feature**: [spec.md](../spec.md)
## Content Quality
- [x] No implementation details (languages, frameworks, APIs)
- [x] Focused on user value and business needs
- [x] Written for non-technical stakeholders
- [x] All mandatory sections completed
## Requirement Completeness
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Requirements are testable and unambiguous
- [x] Success criteria are measurable
- [x] Success criteria are technology-agnostic (no implementation details)
- [x] All acceptance scenarios are defined
- [x] Edge cases are identified
- [x] Scope is clearly bounded
- [x] Dependencies and assumptions identified
## Feature Readiness
- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows
- [x] Feature meets measurable outcomes defined in Success Criteria
- [x] No implementation details leak into specification
## Notes
All items pass validation. The specification is comprehensive and ready for planning phase.
**Validation Details**:
- **Content Quality**: Specification focuses on what needs to be extracted and published (modules, documentation, sanitization) without specifying how to implement the extraction process. Written at appropriate abstraction level for stakeholders.
- **Requirements**: All 29 functional requirements are testable (e.g., FR-002 "All personal domains MUST be replaced" can be verified by searching files, FR-015 "MUST pass nix flake check" can be verified by running the command).
- **Success Criteria**: All 10 success criteria are measurable and technology-agnostic:
- SC-001: Time-based (30 minutes)
- SC-002-003: Binary pass/fail (build success, zero findings)
- SC-004-005: Count-based (lines of code/docs)
- SC-006: Binary (CI runs successfully)
- SC-007-008: Community metrics (stars, issues/PRs)
- SC-009-010: Incident count and frequency
- **User Scenarios**: Five prioritized user stories cover the complete lifecycle from publication (P1) through deployment (P1), contribution (P2), maintenance (P2), and learning (P3). Each has independent test criteria and clear acceptance scenarios.
- **Edge Cases**: Six edge cases identified covering deployment prerequisites, platform compatibility, architecture support, maintenance concerns, and dependency management.
- **Scope**: Clear boundaries defined in "Out of Scope" section (13 items) distinguishing what will and won't be included in v1.0.
- **Dependencies & Assumptions**: 8 dependencies and 11 assumptions documented, covering technical requirements (NixOS packages, tools) and user expectations (familiarity, infrastructure access).
- **No Clarifications Needed**: RFC resolved all major decisions through multi-model consensus, so no [NEEDS CLARIFICATION] markers required.

419
specs/001-extract-matrix-platform/contracts/ci-validation.yaml Normal file
View file

@ -0,0 +1,419 @@
# CI/CD Validation Contract
# Defines automated checks that must pass before merging changes
version: "1.0"
description: "GitHub Actions CI validation requirements for nixos-matrix-platform-template"
# CI workflow configuration
workflow:
name: "CI"
file: ".github/workflows/ci.yml"
triggers:
- push
- pull_request
concurrency:
group: "${{ github.workflow }}-${{ github.ref }}"
cancel-in-progress: true
# Jobs and their contracts
jobs:
# Job 1: Nix validation and builds
validate:
name: "Nix Validation"
runs-on: "ubuntu-latest"
timeout-minutes: 10
failure_action: block-merge
steps:
- step: "checkout"
uses: "actions/checkout@v4"
contract:
must_succeed: true
failure_blocks_merge: true
- step: "install-nix"
uses: "cachix/install-nix-action@v25"
with:
nix_path: "nixpkgs=channel:nixos-24.05"
contract:
must_succeed: true
failure_blocks_merge: true
max_duration_seconds: 120
- step: "nix-flake-check"
name: "Run nix flake check"
command: "nix flake check --all-systems"
contract:
exit_code: 0
must_succeed: true
failure_blocks_merge: true
max_duration_seconds: 120
success_criteria:
- "All flake outputs validate successfully"
- "No syntax errors in Nix files"
- "All module options type-check correctly"
- step: "build-example-vps"
name: "Build example VPS configuration"
command: "nix build .#nixosConfigurations.example-vps.config.system.build.toplevel"
contract:
exit_code: 0
must_succeed: true
failure_blocks_merge: true
max_duration_seconds: 180
success_criteria:
- "example-vps.nix builds without errors"
- "All imported modules resolve correctly"
- "result symlink created"
- step: "build-example-dev"
name: "Build example dev configuration"
command: "nix build .#nixosConfigurations.example-dev.config.system.build.toplevel"
contract:
exit_code: 0
must_succeed: true
failure_blocks_merge: true
max_duration_seconds: 180
success_criteria:
- "example-dev.nix builds without errors"
- "All imported modules resolve correctly"
- "result symlink created"
# Job 2: Security scanning
security:
name: "Security Scanning"
runs-on: "ubuntu-latest"
timeout-minutes: 5
failure_action: block-merge
steps:
- step: "checkout"
uses: "actions/checkout@v4"
with:
fetch-depth: 0 # Full history for gitleaks
contract:
must_succeed: true
failure_blocks_merge: true
- step: "gitleaks-scan"
name: "Run gitleaks secret scanner"
uses: "gitleaks/gitleaks-action@v2"
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
contract:
exit_code: 0
must_succeed: true
failure_blocks_merge: true
max_duration_seconds: 60
success_criteria:
- "Zero secrets detected"
- "No Matrix tokens (syt_)"
- "No Slack tokens (xox*)"
- "No age keys (AGE-SECRET-KEY-*)"
- "No personal emails or domains"
failure_message: |
Secret detected in commit! This is a CRITICAL security issue.
DO NOT MERGE until secrets are removed.
Steps to fix:
1. Identify the secret in the gitleaks report above
2. Remove or replace with placeholder (e.g., REPLACE_WITH_TOKEN)
3. If secret is in git history, consider force-push (if safe)
4. Re-run CI to verify fix
# Job 3: Documentation validation
docs:
name: "Documentation Validation"
runs-on: "ubuntu-latest"
timeout-minutes: 5
failure_action: warn # Non-blocking for docs-only changes
steps:
- step: "checkout"
uses: "actions/checkout@v4"
contract:
must_succeed: true
- step: "markdown-lint"
name: "Lint markdown files"
uses: "DavidAnson/markdownlint-cli2-action@v14"
with:
globs: "**/*.md"
contract:
exit_code: 0
must_succeed: false # Warnings only
max_duration_seconds: 30
success_criteria:
- "Markdown files follow style guide"
- "No broken relative links"
- "Headers properly formatted"
- step: "check-links"
name: "Check for broken links"
uses: "gaurav-nelson/github-action-markdown-link-check@v1"
with:
use-quiet-mode: "yes"
config-file: ".github/markdown-link-check.json"
contract:
exit_code: 0
must_succeed: false # Warnings only
max_duration_seconds: 60
success_criteria:
- "All internal links resolve"
- "External links return 200 OK"
# Branch protection rules (configured via GitHub settings)
branch_protection:
branches:
- name: "main"
protections:
require_pull_request: true
require_approvals: 0 # v1.0 single maintainer
require_status_checks: true
required_checks:
- "Nix Validation"
- "Security Scanning"
dismiss_stale_reviews: false
require_code_owner_reviews: false
restrict_pushes: false # Allow maintainer to push directly if needed
allow_force_pushes: false
allow_deletions: false
# Status check requirements
status_checks:
strict: true # Require branches to be up-to-date before merging
contexts:
- "validate" # Job: Nix Validation
- "security" # Job: Security Scanning
# Validation matrix for different scenarios
validation_scenarios:
# Scenario 1: New module added
new_module:
required_checks:
- "nix flake check passes"
- "Module builds successfully"
- "gitleaks finds no secrets"
- "Module imported by at least one example configuration"
- "Module documented in README or relevant doc"
additional_manual_review:
- "Module follows existing patterns"
- "Options are well-documented"
- "Security hardening applied (if applicable)"
- "No personal configuration remains"
# Scenario 2: Documentation change
docs_only:
required_checks:
- "markdown-lint passes (or warnings explained)"
- "link-check passes (or broken links justified)"
- "gitleaks still passes (no secrets in examples)"
additional_manual_review:
- "Technical accuracy verified"
- "No personal infrastructure references"
- "Examples use generic domains/IPs"
# Scenario 3: Example configuration change
config_change:
required_checks:
- "nix flake check passes"
- "Modified configuration builds successfully"
- "gitleaks finds no secrets"
- "No personal domains/IPs introduced"
additional_manual_review:
- "Configuration still demonstrates intended use case"
- "Comments explain key options"
- "Secrets properly templated"
# Scenario 4: CI/CD workflow change
ci_change:
required_checks:
- "Workflow syntax valid (GitHub validates)"
- "Test run completes successfully"
- "No secrets exposed in workflow logs"
additional_manual_review:
- "Change doesn't weaken security checks"
- "Timeout values reasonable"
- "Failure actions appropriate (block vs warn)"
# Failure handling
failure_policies:
nix_build_failure:
severity: critical
action: block-merge
notification: "PR author + maintainers"
auto_comment: |
## Build Failure
The Nix build failed for this PR. This prevents merging.
**Common causes:**
- Syntax error in .nix file
- Missing import or dependency
- Type error in module options
- Invalid configuration value
**To debug:**
1. Run `nix flake check` locally
2. Run `nix build .#nixosConfigurations.<config-name>` locally
3. Check the error message for file and line number
4. Fix the issue and push updated commit
CI will automatically re-run on push.
secret_detected:
severity: critical
action: block-merge
notification: "PR author + maintainers + security team"
auto_comment: |
## ⚠️ SECRET DETECTED ⚠️
gitleaks has detected a potential secret in this PR.
**CRITICAL: DO NOT MERGE until resolved.**
**Steps to fix:**
1. Review the gitleaks report in the CI logs
2. Identify the secret (token, password, key, etc.)
3. Replace with placeholder or remove entirely
4. If secret is in git history:
- Consider force-push to remove (if safe)
- Or add to .gitignore and create new commit
5. Ensure secret is listed in secrets.yaml.example with generation instructions
6. Re-run CI to verify fix
**If this is a false positive:**
- Add pattern to .gitleaksignore (with justification in comment)
- Document why this is safe in PR description
docs_link_failure:
severity: warning
action: warn
notification: "PR author"
auto_comment: |
## Documentation Link Check Warning
Some links in documentation may be broken.
This is a **warning** - the PR can still be merged if links will be fixed soon.
**Common causes:**
- Link to external site that's temporarily down
- Link to doc that hasn't been created yet
- Typo in relative path
**To fix:**
1. Check the link-check report in CI logs
2. Fix broken links or remove them
3. For external links, verify they're stable/permanent
# Performance budgets
performance:
ci_total_time:
target: "5 minutes"
warning: "8 minutes"
critical: "10 minutes"
nix_flake_check:
target: "1 minute"
warning: "2 minutes"
critical: "3 minutes"
nix_build_per_config:
target: "2 minutes"
warning: "3 minutes"
critical: "5 minutes"
gitleaks_scan:
target: "20 seconds"
warning: "40 seconds"
critical: "60 seconds"
# Notification channels
notifications:
on_failure:
- github-pr-comment
- github-pr-status
on_success:
- github-pr-status
on_critical_failure:
- github-pr-comment
- github-pr-status
- email # If configured
# Metrics to track (post-deployment)
metrics:
ci_success_rate:
target: "> 95%"
measurement: "successful CI runs / total CI runs"
false_positive_rate:
target: "< 5%"
measurement: "false secret detections / total gitleaks runs"
average_ci_duration:
target: "< 5 minutes"
measurement: "mean duration of all CI runs"
time_to_fix_failures:
target: "< 1 hour"
measurement: "time from failure to green CI"
# Integration with GitHub features
github_integrations:
status_checks:
enabled: true
required_for_merge: ["validate", "security"]
auto_merge:
enabled: false # Manual merge for v1.0
discussions:
enabled: true
categories: ["Q&A", "Ideas", "Show and Tell"]
issues:
templates:
- bug_report.yml
- feature_request.yml
code_owners:
file: ".github/CODEOWNERS"
content: |
# Code ownership for nixos-matrix-platform-template
* @maintainer-username
# Security-critical files require extra review
.github/workflows/ @maintainer-username
modules/matrix-secrets/ @maintainer-username
*.sops.yaml @maintainer-username
# Pre-commit hooks (optional for contributors)
pre_commit:
config_file: ".pre-commit-config.yaml"
hooks:
- id: "gitleaks"
name: "gitleaks"
entry: "gitleaks protect --staged"
language: "system"
pass_filenames: false
- id: "nix-flake-check"
name: "nix flake check"
entry: "nix flake check"
language: "system"
pass_filenames: false
stages: [commit]
# Success criteria for CI system itself
ci_success_criteria:
- All jobs complete within performance budgets
- Zero false negatives (secrets not detected)
- < 5% false positives (valid code flagged as secret)
- Status checks correctly block/warn as configured
- Auto-comments provide helpful guidance
- Notifications reach appropriate parties
- Metrics tracked and visible in repository insights

365
specs/001-extract-matrix-platform/contracts/sanitization-rules.yaml Normal file
View file

@ -0,0 +1,365 @@
# Sanitization Rules Contract
# Defines all patterns to find and replace when extracting modules from ops-base
version: "1.0"
description: "Comprehensive sanitization rules for creating nixos-matrix-platform-template from ops-base"
# Critical rules - MUST be applied, validation failures block publication
critical_rules:
- id: 1
name: "Replace primary domain clarun.xyz"
pattern_type: domain
pattern: "clarun\\.xyz"
replacement: "example.com"
applies_to: [code, docs, comments, configs]
validation_method: grep
validation_command: "rg 'clarun\\.xyz' --type nix --type md"
expected_matches: 0
- id: 2
name: "Replace secondary domain talu.uno"
pattern_type: domain
pattern: "talu\\.uno"
replacement: "matrix.example.org"
applies_to: [code, docs, comments, configs]
validation_method: grep
validation_command: "rg 'talu\\.uno' --type nix --type md"
expected_matches: 0
- id: 3
name: "Replace private IP range 192.168.1.x"
pattern_type: ip_address
pattern: "192\\.168\\.1\\.(\\d+)"
replacement: "10.0.0.\\1"
applies_to: [code, configs]
validation_method: regex
validation_command: "rg '192\\.168\\.1\\.' --type nix"
expected_matches: 0
- id: 4
name: "Replace public VPS IP"
pattern_type: ip_address
pattern: "45\\.77\\.205\\.49"
replacement: "203.0.113.10" # TEST-NET-3
applies_to: [code, docs, comments, configs]
validation_method: grep
validation_command: "rg '45\\.77\\.205\\.49'"
expected_matches: 0
- id: 5
name: "Replace personal home path"
pattern_type: path
pattern: "/home/dan"
replacement: "/home/user"
applies_to: [code, docs, comments]
validation_method: grep
validation_command: "rg '/home/dan'"
expected_matches: 0
- id: 6
name: "Replace hostname jrz1"
pattern_type: hostname
pattern: "\\bjrz1\\b"
replacement: "matrix"
applies_to: [code, docs, comments, configs]
validation_method: regex
validation_command: "rg '\\bjrz1\\b' --type nix --type md"
expected_matches: 0
- id: 7
name: "Replace Matrix admin user"
pattern_type: username
pattern: "@admin:clarun\\.xyz"
replacement: "@admin:example.com"
applies_to: [code, docs, configs]
validation_method: grep
validation_command: "rg '@admin:clarun'"
expected_matches: 0
- id: 8
name: "Detect Matrix access tokens"
pattern_type: secret_pattern
pattern: "syt_[a-zA-Z0-9_-]{20,}"
replacement: null # Should not exist
applies_to: [all]
validation_method: gitleaks
validation_command: "gitleaks detect --no-git --source ."
expected_matches: 0
- id: 9
name: "Detect Slack tokens"
pattern_type: secret_pattern
pattern: "xox[baprs]-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,}"
replacement: null # Should not exist
applies_to: [all]
validation_method: gitleaks
validation_command: "gitleaks detect --no-git --source ."
expected_matches: 0
- id: 10
name: "Detect age keys"
pattern_type: secret_pattern
pattern: "AGE-SECRET-KEY-[A-Z0-9]{59}"
replacement: null # Should not exist
applies_to: [all]
validation_method: gitleaks
validation_command: "gitleaks detect --no-git --source ."
expected_matches: 0
# High priority rules - SHOULD be applied, warnings if validation fails
high_priority_rules:
- id: 11
name: "Replace workspace name"
pattern_type: identifier
pattern: "my-workspace"
replacement: "your-workspace"
applies_to: [code, configs]
validation_method: grep
validation_command: "rg 'my-workspace' --type nix"
expected_matches: 0
- id: 12
name: "Replace personal email"
pattern_type: email
pattern: "dlei@duck\\.com"
replacement: "admin@example.com"
applies_to: [code, configs]
validation_method: grep
validation_command: "rg 'dlei@duck\\.com'"
expected_matches: 0
- id: 13
name: "Replace project-specific paths"
pattern_type: path
pattern: "/home/dan/proj/ops-base"
replacement: "/path/to/ops-base"
applies_to: [docs, comments]
validation_method: grep
validation_command: "rg '/home/dan/proj'"
expected_matches: 0
- id: 14
name: "Replace continuwuity local path"
pattern_type: path
pattern: "git\\+file:///home/dan/proj/continuwuity"
replacement: "github:girlbossceo/conduwuit"
applies_to: [code]
validation_method: grep
validation_command: "rg 'git\\+file://'"
expected_matches: 0
- id: 15
name: "Sanitize registration tokens (example values)"
pattern_type: secret_pattern
pattern: "9a3ad59ee136e5a9dc1612cc179c9b7ff8da78c537682aad82c8084e5ae6b5c3"
replacement: "GENERATE_WITH_openssl_rand_hex_32"
applies_to: [docs]
validation_method: grep
validation_command: "rg '9a3ad59ee136e5a9dc1612cc179c9b7ff8da78c537682aad82c8084e5ae6b5c3'"
expected_matches: 0
# Medium priority rules - COULD be applied, informational only
medium_priority_rules:
- id: 16
name: "Add REPLACE_ME comments to domain fields"
pattern_type: comment_addition
pattern: 'serverName = "([^"]+)";'
replacement: 'serverName = "\\1"; # REPLACE: Your Matrix server domain'
applies_to: [code]
validation_method: manual
note: "Add helpful comments to guide users"
- id: 17
name: "Add REPLACE_ME comments to workspace fields"
pattern_type: comment_addition
pattern: 'workspace = "([^"]+)";'
replacement: 'workspace = "\\1"; # REPLACE: Your Slack workspace name'
applies_to: [code]
validation_method: manual
note: "Add helpful comments to guide users"
- id: 18
name: "Sanitize temporary paths"
pattern_type: path
pattern: "/tmp/[a-zA-Z0-9_-]+"
replacement: "/tmp/example-path"
applies_to: [docs]
validation_method: grep
validation_command: "rg '/tmp/[a-zA-Z0-9_-]+' docs/"
expected_matches: 0
# Special rules for worklogs → documentation extraction
worklog_sanitization:
- id: 19
name: "Remove time-stamped session markers"
pattern_type: metadata
pattern: "^\\* \\[\\d{4}-\\d{2}-\\d{2}.*\\].*$"
replacement: null # Delete these lines
applies_to: [worklogs]
validation_method: manual
note: "Remove org-mode timestamps when extracting to markdown"
- id: 20
name: "Sanitize error messages with IPs"
pattern_type: error_context
pattern: "connection to (192\\.168\\.1\\.\\d+|45\\.77\\.205\\.49)"
replacement: "connection to <host>"
applies_to: [worklogs, docs]
validation_method: grep
validation_command: "rg 'connection to (192\\.168|45\\.77)' docs/"
expected_matches: 0
- id: 21
name: "Sanitize SSH commands with real hosts"
pattern_type: command_sanitization
pattern: "ssh root@(45\\.77\\.205\\.49|192\\.168\\.1\\.\\d+)"
replacement: "ssh root@<vps-ip>"
applies_to: [docs]
validation_method: grep
validation_command: "rg 'ssh root@(45\\.77|192\\.168)' docs/"
expected_matches: 0
- id: 22
name: "Sanitize curl commands with real domains"
pattern_type: command_sanitization
pattern: "curl https?://(clarun\\.xyz|talu\\.uno)"
replacement: "curl https://example.com"
applies_to: [docs]
validation_method: grep
validation_command: "rg 'curl.*clarun|curl.*talu' docs/"
expected_matches: 0
# Validation steps (executed in order)
validation_pipeline:
- step: 1
name: "Automated pattern replacement"
script: "scripts/sanitize-files.sh"
input: "staging/"
output: "sanitized/"
- step: 2
name: "Grep validation for critical patterns"
command: |
rg 'clarun\.xyz|talu\.uno|192\.168\.1\.|45\.77\.205\.49|/home/dan|jrz1' \
--type nix --type md sanitized/
expected_exit_code: 1 # No matches
- step: 3
name: "gitleaks secret scanning"
command: "gitleaks detect --no-git --source sanitized/"
expected_exit_code: 0 # No secrets found
- step: 4
name: "Manual review checklist"
checklist:
- "Review all comments for personal context"
- "Check git commit messages (if any preserved)"
- "Scan for personal workspace names"
- "Verify all secret placeholders have REPLACE_ME or generation instructions"
- "Check documentation for personal debugging sessions"
- "Verify example configurations use only generic values"
- step: 5
name: "Nix build validation"
command: |
nix flake check sanitized/
nix build sanitized/#nixosConfigurations.example-vps.config.system.build.toplevel
nix build sanitized/#nixosConfigurations.example-dev.config.system.build.toplevel
expected_exit_code: 0 # All builds succeed
# Post-sanitization verification
verification:
required_placeholders:
- pattern: "example\\.com"
min_occurrences: 10
reason: "Domain must be replaced throughout"
- pattern: "matrix\\.example\\.org"
min_occurrences: 3
reason: "Secondary domain must be replaced"
- pattern: "10\\.0\\.0\\."
min_occurrences: 5
reason: "Private IPs must use RFC 1918"
- pattern: "REPLACE|GENERATE_WITH"
min_occurrences: 5
reason: "User guidance comments required"
forbidden_patterns:
- pattern: "clarun\\.xyz"
max_occurrences: 0
severity: critical
- pattern: "talu\\.uno"
max_occurrences: 0
severity: critical
- pattern: "192\\.168\\.1\\."
max_occurrences: 0
severity: critical
- pattern: "45\\.77\\.205\\.49"
max_occurrences: 0
severity: critical
- pattern: "/home/dan"
max_occurrences: 0
severity: critical
- pattern: "syt_|xox[baprs]-|AGE-SECRET-KEY"
max_occurrences: 0
severity: critical
# Sanitization script integration
script_usage: |
# scripts/sanitize-files.sh usage:
./scripts/sanitize-files.sh <source-dir> <output-dir>
Example:
./scripts/sanitize-files.sh ~/proj/ops-base/modules staging/modules
The script will:
1. Copy files from source to staging
2. Apply all critical_rules in order
3. Apply all high_priority_rules
4. Run validation pipeline
5. Report any failures or warnings
6. Exit 0 if all critical validations pass
# Manual review guide
manual_review_guide: |
After automated sanitization, perform manual review:
1. Read each .nix file:
- Check comments for personal references
- Verify all domains are generic (example.com, matrix.example.org)
- Ensure all IPs use RFC 1918 or TEST-NET ranges
- Look for hardcoded workspace/project names
2. Read all documentation:
- Check for personal debugging notes
- Verify command examples use generic hosts
- Ensure error messages don't expose real infrastructure
- Check screenshots for sensitive data (if any)
3. Review git history (if preserved):
- Scan commit messages for personal context
- Check for accidentally committed secrets
- Verify no ops-base commits included
4. Final validation:
- Run gitleaks on full repository
- Build all example configurations
- Test deployment guide on clean VPS (Phase 3)
# Success criteria
success_criteria:
- All critical_rules validation commands return expected_matches: 0
- All high_priority_rules validation commands return expected_matches: 0
- gitleaks returns 0 findings
- nix flake check succeeds for all configurations
- Manual review checklist 100% complete
- No personal domains/IPs/paths in published repository
- Fresh git history (no ops-base commits)

586
specs/001-extract-matrix-platform/data-model.md Normal file
View file

@ -0,0 +1,586 @@
# Data Model: Extract Matrix Platform Modules
**Date**: 2025-10-11
**Feature**: Extract Matrix Platform Modules as Public Template
## Overview
This document defines the key entities, their attributes, relationships, and lifecycle for the Matrix platform template extraction project. These entities represent both the artifacts being created and the processes managing them.
---
## Entity Diagram
```
┌─────────────────┐
│ ops-base │
│ Repository │
│ (source repo) │
└────────┬────────┘
│ contains
├────────────────┐
│ │
▼ ▼
┌────────┐ ┌──────────┐
│ Module │ │ Worklog │
└───┬────┘ └────┬─────┘
│ │
│ sanitized │ extracted
│ via │ into
│ │
▼ ▼
┌───────────────┐ ┌──────────────┐
│ Sanitization │ │ Pattern │
│ Rule │ │ Document │
└───────┬───────┘ └──────┬───────┘
│ │
│ applied to │ included in
│ │
▼ ▼
┌─────────────────────────────────┐
│ nixos-matrix-platform-template │
│ (output repo) │
└──────────────┬──────────────────┘
│ contains
├──────────┬──────────────┬─────────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌────────┐ ┌────────────┐ ┌────────┐ ┌─────────┐
│ Module │ │Configuration│ │ Secret │ │ Pattern │
│(clean) │ │ (example) │ │Template│ │ Doc │
└────────┘ └────────────┘ └────────┘ └─────────┘
│
│ imports
▼
┌────────┐
│ Module │
└────────┘
```
---
## Core Entities
### 1. Module
**Description**: A reusable NixOS module file providing service configuration and systemd unit definitions.
**Attributes**:
- `name`: string (e.g., "matrix-continuwuity", "mautrix-slack")
- `filepath`: absolute path (e.g., "modules/matrix-continuwuity.nix")
- `line_count`: integer (size metric)
- `service_name`: string (systemd service identifier)
- `dependencies`: array of module names (other modules it depends on)
- `options`: array of configurable options exposed
- `state`: enum [ops-base, staging, sanitized, published]
- `last_modified`: timestamp
- `source_commit`: string (ops-base git commit hash)
**Lifecycle States**:
1. **ops-base**: Original module in private repository
2. **staging**: Copied to sanitization workspace
3. **sanitized**: Processed by sanitization rules, validated
4. **published**: Committed to template repository
**Validation Rules**:
- Must build successfully with `nix flake check`
- Must contain no secrets (gitleaks scan passes)
- All personal domains/IPs replaced
- All paths sanitized
- Options documented with descriptions
**Example**:
```nix
# modules/matrix-continuwuity.nix (sanitized state)
{
name = "matrix-continuwuity"
filepath = "modules/matrix-continuwuity.nix"
line_count = 319
service_name = "continuwuity"
dependencies = ["sops-nix"]
options = ["domain", "port", "enableRegistration", "enableFederation"]
state = "sanitized"
source_commit = "abc123def456"
}
```
**Relationships**:
- **Contains**: Options (1-to-many)
- **Depends on**: Other Modules (many-to-many)
- **Imported by**: Configurations (many-to-many)
- **Created from**: ops-base Module (1-to-1)
---
### 2. Configuration
**Description**: An example deployment configuration file that imports modules and sets options for specific use cases.
**Attributes**:
- `name`: string (e.g., "example-vps", "example-dev")
- `filepath`: absolute path (e.g., "configurations/example-vps.nix")
- `use_case`: string (description of deployment scenario)
- `modules_imported`: array of module names
- `secrets_required`: array of secret names
- `network_config`: enum [public-vps, private-lan, hybrid]
- `state`: enum [draft, validated, documented]
**Lifecycle States**:
1. **draft**: Initial configuration created
2. **validated**: Passes `nix flake check` and builds successfully
3. **documented**: Referenced in getting-started.md or deployment.md
**Validation Rules**:
- Must import at least one module
- Must build successfully as NixOS configuration
- All required secrets must be documented
- Must include comments explaining key options
- Must use example domains/IPs only
**Example**:
```nix
# configurations/example-vps.nix
{
name = "example-vps"
filepath = "configurations/example-vps.nix"
use_case = "Production VPS deployment with Matrix + Forgejo + Slack bridge"
modules_imported = ["matrix-continuwuity", "dev-services", "fail2ban", "ssh-hardening"]
secrets_required = ["matrix-registration-token", "acme-email", "slack-oauth-token"]
network_config = "public-vps"
state = "validated"
}
```
**Relationships**:
- **Imports**: Modules (many-to-many)
- **Requires**: Secrets (many-to-many)
- **Documented in**: Pattern Documents (many-to-many)
---
### 3. Secret
**Description**: Sensitive data (tokens, passwords, keys) managed via sops-nix encryption.
**Attributes**:
- `name`: string (e.g., "matrix-registration-token", "acme-email")
- `type`: enum [token, password, key, email, certificate]
- `storage_path`: string (e.g., "secrets/secrets.yaml")
- `sops_key`: string (YAML path in secrets file)
- `required_by`: array of module/configuration names
- `example_value`: string (placeholder for templates)
- `generation_method`: string (how to generate the secret)
- `rotation_frequency`: enum [never, yearly, quarterly, monthly, as-needed]
**Lifecycle States**:
1. **templated**: Placeholder in secrets.yaml.example
2. **generated**: User creates actual secret value
3. **encrypted**: sops-nix encrypts with age key
4. **deployed**: Secret accessible to systemd service
**Validation Rules**:
- Must never appear in plaintext in git history
- Must have corresponding entry in secrets.yaml.example
- Must have generation instructions in docs/secrets-management.md
- Must specify which services require access
**Example**:
```yaml
# secrets/secrets.yaml (encrypted state)
matrix:
registration_token: ENC[AES256_GCM,data:...,iv:...,tag:...,type:str]
# secrets/secrets.yaml.example (templated state)
matrix:
registration_token: "GENERATE_WITH_openssl_rand_hex_32"
```
**Relationships**:
- **Required by**: Modules (many-to-many)
- **Required by**: Configurations (many-to-many)
- **Encrypted in**: secrets.yaml file (1-to-1)
- **Documented in**: secrets-management.md (1-to-1)
---
### 4. Sanitization Rule
**Description**: A find/replace or validation rule that ensures personal information is removed from files.
**Attributes**:
- `id`: integer (unique identifier)
- `pattern_type`: enum [domain, ip_address, path, username, hostname, secret_pattern]
- `pattern`: string or regex (what to search for)
- `replacement`: string (what to replace with)
- `applies_to`: enum [code, docs, comments, all]
- `validation_method`: enum [grep, gitleaks, regex, manual]
- `priority`: enum [critical, high, medium, low]
**Lifecycle States**:
1. **defined**: Rule created in contracts/sanitization-rules.yaml
2. **automated**: Implemented in scripts/sanitize-files.sh
3. **applied**: Executed on files during sanitization
4. **verified**: Validation confirms no matches remain
**Validation Rules**:
- Pattern must be specific enough to avoid false positives
- Replacement must be valid for context (e.g., valid domain format)
- Must specify which file types/patterns to apply to
- Must have corresponding validation step
**Example**:
```yaml
# contracts/sanitization-rules.yaml
- id: 1
pattern_type: domain
pattern: "clarun\\.xyz"
replacement: "example.com"
applies_to: all
validation_method: grep
priority: critical
- id: 2
pattern_type: ip_address
pattern: "192\\.168\\.1\\.(\\d+)"
replacement: "10.0.0.\\1"
applies_to: code
validation_method: regex
priority: critical
- id: 3
pattern_type: secret_pattern
pattern: "syt_[a-zA-Z0-9]{24}" # Matrix access token
replacement: null # Should not exist, validation only
applies_to: all
validation_method: gitleaks
priority: critical
```
**Relationships**:
- **Applied to**: Modules (many-to-many)
- **Applied to**: Configurations (many-to-many)
- **Applied to**: Pattern Documents (many-to-many)
- **Validated by**: CI/CD pipeline (many-to-1)
---
### 5. Pattern Document
**Description**: Extracted architectural knowledge from worklogs explaining proven implementation approaches.
**Attributes**:
- `title`: string (e.g., "Socket Mode Authentication Pattern")
- `filepath`: absolute path (e.g., "docs/patterns/config-generation.md")
- `category`: enum [pattern, bridge-setup, architecture, deployment, secrets]
- `source_worklogs`: array of worklog filenames
- `modules_referenced`: array of module names
- `prerequisites`: array of strings (what user needs before reading)
- `difficulty`: enum [beginner, intermediate, advanced]
- `word_count`: integer (size metric)
- `last_updated`: timestamp
**Lifecycle States**:
1. **extracted**: Content pulled from worklogs
2. **sanitized**: Personal context removed
3. **structured**: Organized into documentation template
4. **reviewed**: Technical accuracy verified
5. **published**: Committed to template repository
**Validation Rules**:
- Must reference specific modules or code examples
- Must contain actionable steps or explanations
- Must be sanitized (no personal infrastructure references)
- Must link to related documents
- Must include code examples if applicable
**Example**:
```markdown
# docs/patterns/config-generation.md
{
title = "Runtime Configuration Generation Pattern"
filepath = "docs/patterns/config-generation.md"
category = "pattern"
source_worklogs = ["mautrix-slack-bridge-implementation-gmessages-pattern.org"]
modules_referenced = ["mautrix-slack", "mautrix-gmessages"]
prerequisites = ["Understanding of systemd ExecStartPre", "Basic Python knowledge"]
difficulty = "intermediate"
word_count = 800
}
```
**Relationships**:
- **Extracted from**: Worklogs (many-to-1)
- **References**: Modules (many-to-many)
- **Links to**: Other Pattern Documents (many-to-many)
- **Included in**: Template repository (many-to-1)
---
### 6. Sync Checkpoint
**Description**: A record of what changes have been synced from ops-base to template at a specific point in time.
**Attributes**:
- `sync_date`: date (e.g., "2025-10-11")
- `ops_base_commit`: string (git commit hash)
- `template_commit`: string (git commit hash)
- `changes_synced`: array of strings (descriptions)
- `changes_skipped`: array of strings (descriptions with reasons)
- `sync_tag`: string (e.g., "sync-20251011-abc123")
- `synced_by`: string (maintainer name)
- `validation_passed`: boolean (all checks passed)
**Lifecycle States**:
1. **identified**: Changes in ops-base identified for sync
2. **sanitized**: Changes sanitized for template
3. **validated**: CI checks passed
4. **recorded**: Entry added to sync-log.md
5. **tagged**: Git tag created
**Validation Rules**:
- Must reference specific ops-base commit
- Must list all changes (synced and skipped)
- Must pass CI validation before recording
- Must create corresponding git tag
- Must update sync-log.md
**Example**:
```markdown
# sync-log.md entry
## Sync 2025-10-11 (ops-base: abc123)
{
sync_date = "2025-10-11"
ops_base_commit = "abc123def456"
template_commit = "def789abc012"
changes_synced = [
"[BUGFIX] Matrix registration token validation",
"[FEATURE] WhatsApp bridge reconnection logic",
"[SECURITY] sops-nix v0.16.0 upgrade"
]
changes_skipped = [
"Personal config changes in comm-talu-uno.nix (not applicable to template)"
]
sync_tag = "sync-20251011-abc123"
synced_by = "maintainer"
validation_passed = true
}
```
**Relationships**:
- **References**: ops-base commit (1-to-1)
- **Creates**: Template commit (1-to-1)
- **Documents**: Module changes (1-to-many)
- **Recorded in**: sync-log.md (many-to-1)
---
## Supporting Entities
### 7. Bridge Setup Guide
**Description**: Step-by-step documentation for configuring specific Matrix bridges with authentication and registration.
**Attributes**:
- `bridge_name`: string (e.g., "slack", "whatsapp", "gmessages")
- `filepath`: absolute path (e.g., "docs/bridges/slack-setup.md")
- `auth_method`: string (e.g., "Socket Mode OAuth", "QR code pairing")
- `prerequisites`: array of strings
- `estimated_time`: integer (minutes)
- `difficulty`: enum [easy, medium, hard]
- `common_issues`: array of strings (troubleshooting)
**Lifecycle**: Same as Pattern Document
**Example**:
```markdown
# docs/bridges/slack-setup.md
{
bridge_name = "slack"
filepath = "docs/bridges/slack-setup.md"
auth_method = "Socket Mode with App-Level Token"
prerequisites = ["Slack workspace admin access", "Matrix homeserver running"]
estimated_time = 15
difficulty = "medium"
common_issues = [
"Missing OAuth scopes",
"Socket Mode not enabled",
"App-level token vs bot token confusion"
]
}
```
**Relationships**:
- **Documents**: Module (1-to-1)
- **References**: Pattern Documents (many-to-many)
- **Included in**: Template repository (many-to-1)
---
### 8. CI/CD Pipeline
**Description**: Automated validation workflow that runs on every commit/PR.
**Attributes**:
- `name`: string (e.g., "GitHub Actions CI")
- `config_file`: absolute path (".github/workflows/ci.yml")
- `triggers`: array of events (e.g., ["push", "pull_request"])
- `jobs`: array of job names (e.g., ["validate", "security"])
- `validation_steps`: array of strings (what gets checked)
- `failure_action`: enum [block-merge, warn, notify]
- `average_duration`: integer (seconds)
**Validation Steps**:
```yaml
validate:
- nix flake check --all-systems
- nix build .#nixosConfigurations.example-vps
- nix build .#nixosConfigurations.example-dev
security:
- gitleaks detect (full repo scan)
- Check for personal domain/IP patterns
```
**Relationships**:
- **Validates**: Modules (1-to-many)
- **Validates**: Configurations (1-to-many)
- **Enforces**: Sanitization Rules (1-to-many)
- **Reports to**: GitHub PR status (1-to-1)
---
## State Transitions
### Module Lifecycle
```
ops-base (source)
↓ [copy to staging]
staging
↓ [apply sanitization rules]
sanitized
↓ [run validations: nix flake check, gitleaks]
validated
↓ [commit to template repo]
published
↓ [user deploys]
deployed
```
### Sync Checkpoint Lifecycle
```
identified (changes in ops-base)
↓ [review changes]
prioritized (classify: sync vs skip)
↓ [apply sanitization]
sanitized
↓ [run CI validation]
validated
↓ [update sync-log.md, create tag]
recorded
↓ [push to template repo]
published
```
### Secret Lifecycle (user perspective)
```
templated (secrets.yaml.example)
↓ [user copies and edits]
generated (plain yaml)
↓ [sops -e -i secrets.yaml]
encrypted (sops-managed)
↓ [nixos-rebuild deploy]
deployed (/run/secrets/*)
↓ [systemd LoadCredential]
accessible (service can read)
```
---
## Validation Matrix
| Entity Type | Validation Method | Tool | Frequency |
|-------------|------------------|------|-----------|
| Module | Syntax check | `nix flake check` | Every commit |
| Module | Secret scan | `gitleaks` | Every commit |
| Module | Build test | `nix build` | Every commit |
| Module | Manual review | Human checklist | Pre-publication |
| Configuration | Syntax check | `nix flake check` | Every commit |
| Configuration | Build test | `nix build` | Every commit |
| Configuration | Deploy test | VPS integration | Pre-v1.0 |
| Secret | Leakage check | `gitleaks` | Every commit |
| Secret | Template check | Manual review | Pre-publication |
| Sanitization Rule | Pattern match | `grep` / `rg` | After sanitization |
| Sanitization Rule | No false positives | Manual review | Pre-publication |
| Pattern Document | Accuracy | Manual review vs code | Pre-publication |
| Pattern Document | Sanitization | `grep` for personal refs | Pre-publication |
| Sync Checkpoint | Build pass | `nix flake check` | Every sync |
| Sync Checkpoint | No secrets | `gitleaks` | Every sync |
---
## Cardinality Summary
```
ops-base Repository (1)
└── contains Modules (8-10)
└── contains Worklogs (20+)
nixos-matrix-platform-template Repository (1)
├── contains Modules (8-10, sanitized copies)
├── contains Configurations (2)
├── contains Secret Templates (5-10)
├── contains Pattern Documents (10-15)
├── contains Bridge Setup Guides (3)
└── tracked by Sync Checkpoints (4+ per year)
Sanitization Rules (20-30)
└── applied to all template artifacts
CI/CD Pipeline (1)
└── validates all changes (∞ runs)
```
---
## Key Relationships
1. **Module ← depends on → Module**: Dependency graph (e.g., dev-services depends on matrix-continuwuity)
2. **Configuration → imports → Module**: Many-to-many (configs can import multiple modules)
3. **Secret ← required by → Module**: Many-to-many (modules can require multiple secrets)
4. **Sanitization Rule → applied to → Module**: Many-to-many (rules apply to multiple files)
5. **Pattern Document ← extracted from → Worklog**: Many-to-one (multiple docs from one worklog)
6. **Sync Checkpoint → references → Module**: One-to-many (sync updates multiple modules)
---
## Data Storage
### Git Repository (primary storage)
- **Location**: GitHub
- **Access**: Public (template), private (ops-base)
- **Versioning**: Git commits, tags
- **Backup**: GitHub infrastructure + local clones
### Filesystem (workspace)
- **staging/**: Temporary sanitization workspace
- **ops-base/**: Source repository (permanent)
- **nixos-matrix-platform-template/**: Output repository (permanent)
### YAML Files (structured data)
- **contracts/sanitization-rules.yaml**: Sanitization rules
- **contracts/ci-validation.yaml**: CI validation requirements
- **secrets/secrets.yaml.example**: Secret templates
- **sync-log.md**: Sync checkpoint records
---
## Next Steps
This data model will be used to:
1. Generate contracts (sanitization rules, CI validation)
2. Structure task breakdown (what artifacts to create)
3. Define acceptance criteria (validation for each entity)
4. Guide implementation (what to build in what order)

190
specs/001-extract-matrix-platform/plan.md Normal file
View file

@ -0,0 +1,190 @@
# Implementation Plan: Extract Matrix Platform Modules for ops-jrz1 Server
**Branch**: `001-extract-matrix-platform` | **Date**: 2025-10-11 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-extract-matrix-platform/spec.md`
## Summary
Extract production-tested NixOS modules for Matrix homeserver (Continuwuity), mautrix bridges (Slack, WhatsApp, Google Messages), and security hardening from ops-base repository. Sanitize personal information (domains, IPs, secrets, paths) and place in this repository to configure the ops-jrz1 dev/test server. Include deployment documentation and secrets management setup using sops-nix.
**Note**: This is a single-repository project. All extracted modules, configuration, and documentation live in ops-jrz1 repository. Public template sharing is deferred for future.
## Technical Context
**Language/Version**: Nix 2.x, NixOS 24.05+, Bash 5.x (for scripts)
**Primary Dependencies**:
- nixpkgs (pinned for reproducibility)
- sops-nix (secrets management)
- gitleaks (secret scanning via git hooks)
- age (encryption)
- pre-commit framework (git hooks orchestration)
**Storage**: Git repository (Forgejo for development, GitHub/tangl.sh for publication), filesystem-based (NixOS modules as .nix files)
**Testing & Validation**:
- Git pre-commit hooks (block commits with syntax errors or secrets)
- Git pre-push hooks (validate builds before push)
- nix flake check (syntax and build validation)
- gitleaks (secret scanning via hooks)
- Integration testing (deploy to test VPS)
- Manual validation (sanitization review)
**Target Platform**: Linux (NixOS), x86_64-linux architecture
**Project Type**: NixOS server configuration (modules + configuration + documentation)
**Performance Goals**:
- Template clone to working deployment: <30 minutes
- Git pre-commit hook execution: <30 seconds
- Git pre-push hook validation (full build): <5 minutes
- nix flake check: <2 minutes
**Constraints**:
- Zero secrets in published repository (gitleaks must return 0 findings)
- All example configurations must build successfully
- Fresh git history (no ops-base history)
- Manual sync process (scripted helpers only)
**Scale/Scope**:
- 6+ core NixOS modules to extract (matrix-continuwuity, 3 bridges, 2 security)
- Core documentation (README, deployment guide, secrets-management)
- Configuration for ops-jrz1 dev/test server
- 29 functional requirements (some deferred for public sharing)
- 5 user stories (US3 deferred, US1/US2/US4/US5 active)
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
**Status**: No project constitution defined yet. This is an infrastructure extraction project with established RFC.
**Key Constraints Derived from Feature Spec**:
1. ✅ **Security First**: Zero tolerance for secret leakage (gitleaks validation mandatory)
2. ✅ **Reproducibility**: All builds must be deterministic (pinned nixpkgs)
3. ✅ **Testability**: All configurations must validate before publication
4. ✅ **Documentation Quality**: Extracted patterns must be comprehensive and sanitized
5. ✅ **Community Governance**: Clear contribution and security policies required
**No violations identified** - This is a one-time extraction project following established RFC guidelines.
## Project Structure
### Documentation (this feature)
```
specs/001-extract-matrix-platform/
├── spec.md # Feature specification (completed)
├── plan.md # This file (/speckit.plan command output)
├── research.md # Phase 0 output (technical decisions & patterns)
├── data-model.md # Phase 1 output (entities: modules, configs, secrets)
├── quickstart.md # Phase 1 output (developer quick start)
├── contracts/ # Phase 1 output (sanitization rules, CI contracts)
│ ├── sanitization-rules.yaml
│ └── ci-validation.yaml
└── tasks.md # Phase 2 output (/speckit.tasks command)
```
### Source Code (repository root)
Single repository structure (ops-jrz1). Everything lives here:
```
# ops-jrz1 (this repo): Server config + planning + extracted modules
specs/001-extract-matrix-platform/ # Planning docs (speckit workflow)
├── spec.md, plan.md, tasks.md
├── research.md, data-model.md
└── contracts/
staging/ # Temporary extraction workspace
├── modules/ # Copied from ops-base (unsanitized)
├── configurations/
└── docs/
modules/ # Extracted & sanitized modules
├── matrix-continuwuity.nix
├── mautrix-slack.nix
├── mautrix-whatsapp.nix
├── mautrix-gmessages.nix
├── security/
│ ├── fail2ban.nix
│ └── ssh-hardening.nix
└── matrix-secrets/
└── default.nix
hosts/ # Server-specific configs
└── ops-jrz1.nix # ops-jrz1 server configuration
docs/ # Deployment documentation
├── deployment.md
├── secrets-management.md
└── bridges/ # Optional bridge setup notes
├── slack-setup.md
├── whatsapp-setup.md
└── gmessages-setup.md
secrets/ # sops-nix encrypted secrets
├── secrets.yaml # Encrypted (gitignored)
└── .sops.yaml # sops configuration
scripts/ # Helper scripts
├── sanitize-files.sh # Apply sanitization rules
└── validate-config.sh # Pre-deploy validation
flake.nix # Server flake configuration
flake.lock # Locked dependencies
configuration.nix # Main server configuration
README.md # Repository overview
LICENSE # MIT license (optional)
```
**Structure Decision**: Single-repository approach where ops-jrz1 contains planning docs, extracted modules, and server configuration. Public template sharing is deferred - focus is on getting ops-jrz1 server working.
## Complexity Tracking
*No constitution violations - this section not applicable*
## Phase 0: Research & Decision Points ✅ COMPLETE
**Status**: All research completed and documented in `research.md`
**Decisions Made**:
1. **Sanitization Strategy**: ✅ Hybrid approach (automated + manual validation)
2. **Worklog Extraction**: ✅ LLM-assisted selective extraction with manual review
3. **Validation Strategy**: ✅ Git hooks (pre-commit/pre-push) with gitleaks + nix flake check
4. **Sync Workflow Design**: ✅ Git tags + sync-log.md + quarterly calendar
5. **Testing Strategy**: ✅ Build validation + selective VPS integration testing
**Artifacts Generated**:
- ✅ `research.md` - 6 major decisions documented with rationale
- ✅ Technology stack defined (Nix, NixOS, sops-nix, gitleaks, pre-commit framework)
- ✅ Risk mitigations documented
- ✅ Success metrics defined
---
## Phase 1: Design & Contracts ✅ COMPLETE
**Status**: All design artifacts created and validated
**Artifacts Generated**:
- ✅ `data-model.md` - 8 core entities with lifecycle states, relationships, validation rules
- ✅ `contracts/sanitization-rules.yaml` - 22 sanitization rules (critical, high, medium priority)
- ✅ `contracts/ci-validation.yaml` - CI/CD pipeline specification with job contracts
- ✅ `quickstart.md` - 4-week implementation guide with day-by-day breakdown
- ✅ `CLAUDE.md` - Agent context updated with Nix, NixOS, Git repository stack
**Design Highlights**:
- **Data Model**: Module, Configuration, Secret, Sanitization Rule, Pattern Document, Sync Checkpoint, Bridge Setup Guide, CI/CD Pipeline
- **22 Sanitization Rules**: Domains (clarun.xyz→example.com), IPs (192.168.1.x→10.0.0.x), paths, secrets, personal references
- **CI Contracts**: nix flake check, gitleaks scan, build validation for example configs
- **Validation Pipeline**: 5-step process from automated replacement to manual review
---
## Phase 2: Task Generation (Next Step)
**Status**: Ready for `/speckit.tasks` command
Use `/speckit.tasks` to generate actionable task breakdown from the design artifacts above. This will create `tasks.md` with dependency-ordered implementation tasks organized by:
- Repository setup and sanitization
- Documentation extraction
- Testing and validation
- Sync workflow and publication

747
specs/001-extract-matrix-platform/quickstart.md Normal file
View file

@ -0,0 +1,747 @@
# Quick Start: Extract Matrix Platform Modules
**Target Audience**: Maintainer extracting modules from ops-base
**Time Required**: 2-4 weeks (following RFC timeline)
**Prerequisites**: Access to ops-base repository, NixOS knowledge, GitHub account
---
## Overview
This guide walks through extracting Matrix platform modules from the private ops-base repository and publishing them as the public nixos-matrix-platform-template. Follow the RFC's 4-week implementation plan.
```
Week 1: Repository setup, sanitization, CI/CD
Week 2: Documentation extraction from worklogs
Week 3: Integration testing and security validation
Week 4: Sync workflow and publication
```
---
## Prerequisites Checklist
Before starting:
- [ ] Access to ops-base repository (`~/proj/ops-base`)
- [ ] Read the RFC (`~/proj/ops-base/docs/rfcs/repository-publication-strategy-rfc.md`)
- [ ] Nix 2.x installed and functional
- [ ] gitleaks 8.18.0+ installed (`nix-shell -p gitleaks`)
- [ ] GitHub account with ability to create public repositories
- [ ] ops-jrz1 repository cloned (this planning repo)
- [ ] Fresh VPS or VM for Phase 3 testing (Vultr/DigitalOcean recommended)
---
## Phase 1: Repository Setup & Sanitization (Week 1)
### Day 1-2: Create Repository and CI/CD
**1. Create GitHub repository:**
```bash
# On GitHub web interface:
# - Name: nixos-matrix-platform-template
# - Description: "Production-ready NixOS modules for Matrix homeserver with bridges"
# - Public repository
# - Initialize with README: No (we'll add it)
# - License: MIT
# Clone locally:
cd ~/proj
git clone git@github.com:YOUR_USERNAME/nixos-matrix-platform-template.git
cd nixos-matrix-platform-template
```
**2. Create initial repository structure:**
```bash
# Create directory structure
mkdir -p modules/{security,matrix-secrets}
mkdir -p configurations
mkdir -p docs/{bridges,patterns}
mkdir -p examples
mkdir -p scripts
mkdir -p .github/{workflows,ISSUE_TEMPLATE}
# Create .gitignore
cat > .gitignore <<'EOF'
# Nix build results
result
result-*
# Secrets (only encrypted versions committed)
secrets/secrets.yaml
!secrets/secrets.yaml.example
# IDE
.vscode/
.idea/
# Temporary files
*.swp
*.swo
*~
.DS_Store
EOF
```
**3. Set up GitHub Actions CI:**
```bash
# Copy CI workflow from contracts
cp ~/proj/ops-jrz1/specs/001-extract-matrix-platform/contracts/ci-validation.yaml \
.github/workflows/ci.yml
# Edit ci.yml to convert from contract format to GitHub Actions YAML
# (See contracts/ci-validation.yaml for structure)
```
**4. Set up pre-commit hooks (optional):**
```bash
cat > .pre-commit-config.yaml <<'EOF'
repos:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.18.0
hooks:
- id: gitleaks
- repo: local
hooks:
- id: nix-flake-check
name: nix flake check
entry: nix flake check
language: system
pass_filenames: false
EOF
```
**5. Create initial README:**
```bash
cat > README.md <<'EOF'
# NixOS Matrix Platform Template
Production-ready NixOS modules for deploying Matrix homeserver with bridges.
**Status**: 🚧 Under construction - not yet ready for use
## Features (planned)
- ✅ Matrix Homeserver (Continuwuity)
- ✅ Bridge Support (Slack, WhatsApp, Google Messages)
- ✅ Development Platform (Forgejo integration)
- ✅ Secrets Management (sops-nix)
- ✅ Security Hardening (fail2ban, SSH)
- ✅ Production Tested
## Coming Soon
Documentation and modules being extracted from production deployment.
Expected completion: [DATE]
## License
MIT License - see [LICENSE](LICENSE)
EOF
```
**6. Add LICENSE file:**
```bash
# Copy MIT license template
cat > LICENSE <<'EOF'
MIT License
Copyright (c) 2025 [Your Name]
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
[... rest of MIT license ...]
EOF
```
**7. Initial commit:**
```bash
git add .
git commit -m "Initial repository structure
- Add directory layout for modules, docs, examples
- Add GitHub Actions CI with nix flake check + gitleaks
- Add MIT license
- Add initial README (work in progress)"
git push origin main
```
### Day 3-5: Copy and Sanitize Modules
**1. Create staging area:**
```bash
cd ~/proj/ops-jrz1
mkdir -p staging/{modules,configurations}
```
**2. Copy modules from ops-base:**
```bash
# Copy core modules
cp ~/proj/ops-base/modules/matrix-continuwuity.nix staging/modules/
cp ~/proj/ops-base/modules/mautrix-slack.nix staging/modules/
cp ~/proj/ops-base/modules/mautrix-whatsapp.nix staging/modules/
cp ~/proj/ops-base/modules/mautrix-gmessages.nix staging/modules/
cp ~/proj/ops-base/modules/dev-services.nix staging/modules/
cp -r ~/proj/ops-base/modules/security staging/modules/
cp -r ~/proj/ops-base/modules/matrix-secrets staging/modules/
# Copy example configurations (will be sanitized to examples)
cp ~/proj/ops-base/configurations/vultr-dev.nix staging/configurations/example-vps.nix
cp ~/proj/ops-base/configurations/dev-vps.nix staging/configurations/example-dev.nix
```
**3. Create sanitization script:**
```bash
cat > scripts/sanitize-files.sh <<'SCRIPT'
#!/usr/bin/env bash
# Automated sanitization based on contracts/sanitization-rules.yaml
set -euo pipefail
SRC_DIR="${1:?Usage: $0 <source-dir> <output-dir>}"
OUT_DIR="${2:?Usage: $0 <source-dir> <output-dir>}"
echo "=== Sanitizing files from $SRC_DIR to $OUT_DIR ==="
# Copy files to output
mkdir -p "$OUT_DIR"
cp -r "$SRC_DIR"/* "$OUT_DIR/"
# Apply critical sanitization rules (from contracts/sanitization-rules.yaml)
echo "Applying domain replacements..."
find "$OUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i \
-e 's/clarun\.xyz/example.com/g' \
-e 's/talu\.uno/matrix.example.org/g' \
{} +
echo "Applying IP address replacements..."
find "$OUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i \
-e 's/192\.168\.1\./10.0.0./g' \
-e 's/45\.77\.205\.49/203.0.113.10/g' \
{} +
echo "Applying path replacements..."
find "$OUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i \
-e 's#/home/dan#/home/user#g' \
-e 's#git+file:///home/dan/proj/continuwuity#github:girlbossceo/conduwuit#g' \
{} +
echo "Applying hostname/username replacements..."
find "$OUT_DIR" -type f \( -name "*.nix" -o -name "*.md" \) -exec sed -i \
-e 's/\bjrz1\b/matrix/g' \
-e 's/@admin:clarun/@admin:example/g' \
-e 's/my-workspace/your-workspace/g' \
-e 's/dlei@duck\.com/admin@example.com/g' \
{} +
echo "Sanitization complete."
echo ""
echo "Next steps:"
echo "1. Run validation: ./scripts/validate-sanitization.sh $OUT_DIR"
echo "2. Manual review: Check comments, docs for personal context"
echo "3. Copy to template repo if validation passes"
SCRIPT
chmod +x scripts/sanitize-files.sh
```
**4. Create validation script:**
```bash
cat > scripts/validate-sanitization.sh <<'SCRIPT'
#!/usr/bin/env bash
# Validate sanitization based on contracts/sanitization-rules.yaml
set -euo pipefail
TARGET_DIR="${1:?Usage: $0 <directory>}"
echo "=== Validating sanitization in $TARGET_DIR ==="
FAILED=0
# Check for forbidden patterns
echo "Checking for personal domains..."
if rg 'clarun\.xyz|talu\.uno' "$TARGET_DIR" --type nix --type md; then
echo "❌ FAILED: Personal domains found"
FAILED=1
else
echo "✅ PASSED: No personal domains"
fi
echo "Checking for personal IPs..."
if rg '192\.168\.1\.|45\.77\.205\.49' "$TARGET_DIR" --type nix --type md; then
echo "❌ FAILED: Personal IPs found"
FAILED=1
else
echo "✅ PASSED: No personal IPs"
fi
echo "Checking for personal paths..."
if rg '/home/dan' "$TARGET_DIR"; then
echo "❌ FAILED: Personal paths found"
FAILED=1
else
echo "✅ PASSED: No personal paths"
fi
echo "Running gitleaks..."
if gitleaks detect --no-git --source "$TARGET_DIR"; then
echo "✅ PASSED: No secrets detected"
else
echo "❌ FAILED: Secrets detected by gitleaks"
FAILED=1
fi
if [ $FAILED -eq 0 ]; then
echo ""
echo "✅ All validations passed!"
echo "Ready for manual review and copy to template repository."
exit 0
else
echo ""
echo "❌ Some validations failed. Review output above."
exit 1
fi
SCRIPT
chmod +x scripts/validate-sanitization.sh
```
**5. Run sanitization:**
```bash
# Sanitize modules
./scripts/sanitize-files.sh staging/modules ~/proj/nixos-matrix-platform-template/modules
# Sanitize configurations
./scripts/sanitize-files.sh staging/configurations ~/proj/nixos-matrix-platform-template/configurations
```
**6. Validate sanitization:**
```bash
./scripts/validate-sanitization.sh ~/proj/nixos-matrix-platform-template/modules
./scripts/validate-sanitization.sh ~/proj/nixos-matrix-platform-template/configurations
```
**7. Manual review (checklist from contracts/sanitization-rules.yaml):**
```bash
# Open each file and review:
# - [ ] Comments contain no personal references
# - [ ] Domain/IP placeholders are clear
# - [ ] REPLACE_ME comments added where needed
# - [ ] No hardcoded tokens or secrets
# - [ ] Module options have descriptions
```
### Day 6-7: Create Examples and Governance Docs
**1. Create example secrets template:**
```bash
cat > ~/proj/nixos-matrix-platform-template/examples/secrets.yaml.example <<'EOF'
# Example secrets file for sops-nix
# See docs/secrets-management.md for setup instructions
matrix:
registration_token: "GENERATE_WITH_openssl_rand_hex_32"
acme:
email: "your-email@example.com"
slack:
oauth_token: "REPLACE_WITH_SLACK_BOT_TOKEN"
app_token: "REPLACE_WITH_SLACK_APP_TOKEN"
# Add more secrets as needed
EOF
```
**2. Create sops config template:**
```bash
cat > ~/proj/nixos-matrix-platform-template/examples/.sops.yaml.example <<'EOF'
keys:
# Replace with your host's age key
# Get it with: ssh-to-age < /etc/ssh/ssh_host_ed25519_key.pub
- &your_host age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
creation_rules:
- path_regex: secrets/secrets\.yaml$
key_groups:
- age:
- *your_host
EOF
```
**3. Create CONTRIBUTING.md:**
```bash
cat > ~/proj/nixos-matrix-platform-template/CONTRIBUTING.md <<'EOF'
# Contributing to nixos-matrix-platform-template
Thank you for contributing!
## How to Contribute
### Bug Reports
- Check existing issues first
- Provide minimal reproduction steps
- Include NixOS version and platform
- Sanitize logs (remove domains/IPs)
### Pull Requests
- Fork repository
- Create feature branch
- Test with `nix flake check`
- Update documentation
- Ensure CI passes (nix build + gitleaks)
- Submit PR with clear description
## Development Workflow
1. Make changes
2. Test locally: `nix flake check`
3. Scan for secrets: `gitleaks detect --no-git`
4. Build examples: `nix build .#nixosConfigurations.example-vps`
5. Submit PR
## Code Standards
- Follow existing Nix style
- Add comments for complex logic
- Use generic examples (example.com, 10.0.0.x)
- No secrets in commits
## Maintenance Policy
- Security fixes: Priority
- Bug fixes: Within 2 weeks
- Features: Best effort
## Questions?
- GitHub Discussions for design/questions
- Issues for bugs only
EOF
```
**4. Create SECURITY.md:**
```bash
cat > ~/proj/nixos-matrix-platform-template/SECURITY.md <<'EOF'
# Security Policy
## Reporting Vulnerabilities
**DO NOT** open public issues for security vulnerabilities.
Email: your-email@example.com
Include:
- Description
- Steps to reproduce
- Potential impact
- Suggested fix (if available)
Response time: 48 hours
Fix timeline: 7 days critical, 30 days moderate
## Supported Versions
| Version | Supported |
|---------|-----------|
| 1.x | ✅ Yes |
| < 1.0 | ❌ No |
EOF
```
**5. Commit governance files:**
```bash
cd ~/proj/nixos-matrix-platform-template
git add examples/ CONTRIBUTING.md SECURITY.md
git commit -m "Add example templates and governance docs
- Add secrets.yaml.example and .sops.yaml.example
- Add CONTRIBUTING.md with contribution guidelines
- Add SECURITY.md with vulnerability disclosure process"
git push origin main
```
---
## Phase 2: Documentation Extraction (Week 2)
### Day 8-10: Extract Architecture Docs
**1. Extract gmessages config pattern:**
```bash
# Use LLM to extract from worklog:
# Input: ~/proj/ops-base/docs/worklogs/mautrix-slack-bridge-implementation-gmessages-pattern.org
# Output: ~/proj/nixos-matrix-platform-template/docs/patterns/config-generation.md
# Focus: Runtime config regeneration pattern, deep_update merge logic
```
**2. Extract admin room setup:**
```bash
# Input: ~/proj/ops-base/docs/worklogs/conduwuit-admin-room-discovery-password-reset.org
# Output: ~/proj/nixos-matrix-platform-template/docs/patterns/admin-room-setup.md
# Focus: Admin room discovery, appservice registration via admin room
```
**3. Extract secrets management:**
```bash
# Input: ~/proj/ops-base/docs/sops-nix-secrets-management-rfc.md
# Output: ~/proj/nixos-matrix-platform-template/docs/secrets-management.md
# Focus: sops-nix setup, age key generation, secret rotation
```
### Day 11-13: Write Bridge Guides
**4. Extract Slack bridge guide:**
```bash
# Input: ~/proj/ops-base/docs/worklogs/mautrix-slack-socket-mode-oauth-scopes-blocker.org
# Output: ~/proj/nixos-matrix-platform-template/docs/bridges/slack-setup.md
# Focus: Socket Mode vs webhooks, OAuth scopes, app configuration
```
**5. Create WhatsApp and gmessages guides:**
```bash
# Based on module configurations and common setup patterns
# Output: docs/bridges/whatsapp-setup.md
# Output: docs/bridges/gmessages-setup.md
```
### Day 14: Create Getting Started Guide
**6. Write comprehensive getting started:**
```bash
# Output: ~/proj/nixos-matrix-platform-template/docs/getting-started.md
# Structure:
# - 5-minute quick start
# - Prerequisites checklist
# - Step-by-step deployment
# - Common issues and solutions
```
---
## Phase 3: Testing and Validation (Week 3)
### Day 15-17: Integration Testing
**1. Deploy to fresh VPS:**
```bash
# Provision fresh NixOS VPS (Vultr/DigitalOcean)
# Time the deployment process (target: <30 minutes)
# Follow getting-started.md exactly as written
# Document any issues or unclear steps
```
**2. Test all user stories:**
```bash
# User Story 1: Developer deploys from template
# - Clone repo: ✅ / ❌
# - Customize config: ✅ / ❌
# - Deploy: ✅ / ❌
# - Matrix responds: ✅ / ❌
# User Story 3: Developer contributes
# - Fork repo: ✅ / ❌
# - Make change: ✅ / ❌
# - CI passes: ✅ / ❌
```
### Day 18-19: Security Review
**3. Final security audit:**
```bash
# Run gitleaks on full repo
cd ~/proj/nixos-matrix-platform-template
gitleaks detect --no-git --source .
# Manual review for personal info
rg 'clarun|talu|192\.168\.1\.|45\.77|/home/dan|jrz1|dlei@duck'
# Review git history (should be clean)
git log --all --oneline
# Test deployment guide on clean machine
```
### Day 20-21: Community Beta Testing
**4. Invite beta testers:**
```bash
# Share repo with 3-5 trusted community members
# Collect feedback on:
# - Documentation clarity
# - Deployment success
# - Missing information
# - Confusing steps
```
---
## Phase 4: Sync Workflow & Publication (Week 4)
### Day 22-23: Document Sync Workflow
**1. Create sync script:**
```bash
# Create scripts/sync-to-template.sh
# Based on research.md Decision 4
```
**2. Create sync-log.md:**
```bash
cat > ~/proj/nixos-matrix-platform-template/sync-log.md <<'EOF'
# Sync Log: ops-base → nixos-matrix-platform-template
This file tracks changes synced from the private ops-base repository.
## Initial Publication (2025-10-11)
**ops-base commit:** [hash]
**template tag:** v1.0.0
**Initial modules:**
- matrix-continuwuity.nix
- mautrix-slack.nix
- mautrix-whatsapp.nix
- mautrix-gmessages.nix
- dev-services.nix
- security/fail2ban.nix
- security/ssh-hardening.nix
- matrix-secrets/default.nix
**Documentation:**
- Extracted from 300KB+ worklogs
- Sanitized for public consumption
- Tested with beta users
EOF
```
### Day 24-25: Final Polish
**3. Update README:**
```bash
# Expand README with:
# - Feature list
# - Quick start link
# - Architecture overview
# - Community links
# - Badges (CI status, license)
```
**4. Create v1.0.0 release:**
```bash
git tag v1.0.0
git push --tags
```
### Day 26-28: Publication
**5. Final validation:**
```bash
# ✅ All CI checks pass
# ✅ gitleaks returns 0 findings
# ✅ All example configs build
# ✅ Documentation complete
# ✅ Beta testing feedback addressed
# ✅ LICENSE and governance files present
```
**6. Make repository public:**
```bash
# GitHub Settings → Change repository visibility → Make public
```
**7. Announce:**
```bash
# Post to:
# - Matrix.org community (#nix:nixos.org)
# - NixOS Discourse
# - Reddit r/NixOS
# - Hacker News (Show HN)
# - Personal blog/social
```
---
## Success Metrics
After publication, track:
- ✅ SC-001: Deployment time <30 minutes (tested in Phase 3)
- ✅ SC-002: All builds pass (CI badge green)
- ✅ SC-003: gitleaks 0 findings (CI validates)
- ✅ SC-004: All 8 modules present and building (checklist: matrix-continuwuity, mautrix-slack, mautrix-whatsapp, mautrix-gmessages, dev-services, fail2ban, ssh-hardening, matrix-secrets)
- ✅ SC-005: All 8 documentation sections complete (checklist: getting-started.md, architecture.md, secrets-management.md, 3 bridge guides, 2 pattern docs)
- 📊 SC-007: 10+ stars in 3 months (GitHub insights)
- 📊 SC-008: 3+ issues/PRs in 3 months (GitHub insights)
- 📊 SC-009: 0 security incidents in 6 months (monitor issues)
- 📊 SC-010: Quarterly syncs (check sync-log.md)
---
## Troubleshooting
### Common Issues
**Issue: gitleaks fails in CI**
```bash
# Check which file triggered
# Review contracts/sanitization-rules.yaml for pattern
# Add to sanitization script if valid pattern
# Or add to .gitleaksignore if false positive
```
**Issue: nix flake check fails**
```bash
# Run locally: nix flake check
# Check error message for file/line
# Common causes:
# - Missing import
# - Syntax error
# - Invalid option type
```
**Issue: Personal info found during review**
```bash
# Add to sanitization script
# Re-run sanitization on affected files
# Run validation again
# Force-push if already committed
```
---
## Next Steps
After v1.0.0 publication:
1. Monitor GitHub issues and discussions
2. Set quarterly calendar reminder for sync (January, April, July, October)
3. Respond to community feedback
4. Plan v1.1 improvements based on usage
5. Consider adding: Cachix, more bridges, monitoring stack
---
## Reference Documents
- **Feature Spec**: `specs/001-extract-matrix-platform/spec.md`
- **Implementation Plan**: `specs/001-extract-matrix-platform/plan.md`
- **Research**: `specs/001-extract-matrix-platform/research.md`
- **Data Model**: `specs/001-extract-matrix-platform/data-model.md`
- **Contracts**: `specs/001-extract-matrix-platform/contracts/`
- **RFC**: `~/proj/ops-base/docs/rfcs/repository-publication-strategy-rfc.md`
---
## Questions?
Refer to research.md for detailed technical decisions, or review the RFC for rationale behind the overall approach.

469
specs/001-extract-matrix-platform/research.md Normal file
View file

@ -0,0 +1,469 @@
# Research: Extract Matrix Platform Modules
**Date**: 2025-10-11
**Feature**: Extract Matrix Platform Modules as Public Template
**Status**: Completed
## Overview
This document captures technical decisions and research findings for extracting Matrix platform modules from ops-base and publishing as a public template. All decisions are informed by the RFC multi-model consensus validation (gemini-2.5-pro, gpt-5-codex, qwen3-coder).
## Decision 1: Sanitization Strategy
### Decision
**Hybrid approach**: Automated script for bulk replacements + manual validation checklist
### Rationale
1. **Safety**: Multiple validation layers reduce risk of missed sensitive data
2. **Efficiency**: Automated script handles 90% of repetitive replacements
3. **Accuracy**: Manual review catches context-specific issues (comments, documentation)
4. **Auditability**: Checklist provides proof of thorough review
5. **RFC Consensus**: All three models recommended this approach
### Implementation
```bash
# scripts/sanitize-files.sh
# Automated replacements:
- clarun.xyz → example.com
- talu.uno → matrix.example.org
- 192.168.1.x → 10.0.0.x (RFC 1918)
- 45.77.205.49 → 203.0.113.10 (TEST-NET-3)
- /home/dan → /home/user
- jrz1 → matrix
- @admin:clarun → @admin:example
# Manual validation checklist:
- Grep for known sensitive patterns
- Review all comments for personal context
- Scan git commit messages if preserved
- Check for hardcoded tokens/secrets
- Verify REPLACE_ME comments added
- Run gitleaks for automated secret detection
```
### Alternatives Considered
- **git-filter-repo**: Rejected - creates modified history, we want fresh history
- **Fully manual**: Rejected - too error-prone for 3,400+ lines
- **Fully automated**: Rejected - can't detect context-specific personal info
### References
- RFC Section: "Enhanced Sanitization Process" (lines 305-375)
- gitleaks documentation: https://github.com/gitleaks/gitleaks
- NixOS security best practices
---
## Decision 2: Worklog Extraction Process
### Decision
**LLM-assisted selective extraction** with manual review and organization
### Rationale
1. **Volume**: 300KB+ of worklogs too large for purely manual extraction
2. **Quality**: LLM can identify and extract architectural patterns effectively
3. **Structure**: Human organization ensures docs follow consistent template
4. **Sanitization**: Manual review removes personal debugging context
5. **Precedent**: Successfully used for RFC creation
### Implementation
```
# Process for each worklog file:
1. Identify extractable content:
- Architectural decisions (KEEP)
- Pattern documentation (KEEP)
- Problem-solving approaches (KEEP, sanitize)
- Personal debugging sessions (SKIP)
- Time-stamped logs (SKIP)
- IP/domain-specific troubleshooting (SANITIZE)
2. Extract with LLM:
- Input: worklog file + target doc structure
- Output: Draft documentation section
- Prompt: "Extract technical patterns, remove personal context"
3. Manual review:
- Verify accuracy against source code
- Remove remaining personal references
- Ensure consistency with other docs
- Add cross-references and examples
4. Target mapping:
- Socket Mode pattern → docs/bridges/slack-setup.md
- Config generation → docs/patterns/config-generation.md
- Admin room setup → docs/patterns/admin-room-setup.md
- sops-nix workflow → docs/secrets-management.md
```
### Alternatives Considered
- **Full manual extraction**: Rejected - too time-consuming, inconsistent
- **Direct copy-paste**: Rejected - contains personal info, lacks structure
- **Automated extraction only**: Rejected - loses nuance, creates poor docs
### Target Documents (from worklogs)
| Worklog Source | Target Documentation |
|----------------|---------------------|
| mautrix-slack-bridge-implementation-gmessages-pattern.org | docs/patterns/config-generation.md |
| mautrix-slack-socket-mode-oauth-scopes-blocker.org | docs/bridges/slack-setup.md |
| conduwuit-admin-room-discovery-password-reset.org | docs/patterns/admin-room-setup.md |
| sops-nix-secrets-management-rfc.md | docs/secrets-management.md |
| (various debugging logs) | docs/troubleshooting.md (optional) |
---
## Decision 3: CI/CD Implementation
### Decision
**GitHub Actions with nix flake check + gitleaks**, no Cachix for v1.0
### Rationale
1. **Simplicity**: GitHub Actions native to platform, no additional services
2. **Security**: gitleaks catches secrets in every PR/commit
3. **Validation**: nix flake check ensures all configs build
4. **Cost**: Free for public repos, no Cachix subscription needed
5. **RFC Alignment**: Matches RFC automated validation requirements
### Implementation
```yaml
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: cachix/install-nix-action@v25
- name: Run nix flake check
run: nix flake check --all-systems
- name: Build example configurations
run: |
nix build .#nixosConfigurations.example-vps.config.system.build.toplevel
nix build .#nixosConfigurations.example-dev.config.system.build.toplevel
security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run gitleaks
uses: gitleaks/gitleaks-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
### Alternatives Considered
- **Cachix integration**: Deferred to v1.1 - adds complexity, build times acceptable without it
- **GitLab CI**: Rejected - GitHub is primary platform for NixOS community
- **Local-only validation**: Rejected - PR validation critical for community contributions
### Performance Targets
- Total CI time: <5 minutes per commit
- nix flake check: <2 minutes
- gitleaks scan: <30 seconds
- Build examples: <3 minutes
---
## Decision 4: Sync Workflow Design
### Decision
**Git tags + sync-log.md file** with quarterly calendar reminders
### Rationale
1. **Traceability**: Git tags mark template versions synced with ops-base state
2. **Documentation**: sync-log.md records what changed and why
3. **Simplicity**: No complex tooling, standard git workflow
4. **Discoverability**: sync-log.md visible in repo for transparency
5. **RFC Consensus**: Documented workflow reduces sync discipline risk
### Implementation
```bash
# scripts/sync-to-template.sh workflow:
1. Identify changes in ops-base since last sync:
git log --since="$(git -C ../nixos-matrix-platform-template tag -l 'sync-*' --sort=-v:refname | head -1 | cut -d'-' -f2)"
2. Review changes for applicability:
- Bug fixes: SYNC
- New features: SYNC if tested
- Security fixes: SYNC (priority)
- Personal config: SKIP
- Worklogs: SKIP
3. Apply sanitization to selected changes
4. Validate in template:
nix flake check
gitleaks detect --no-git
5. Update sync-log.md:
## Sync 2025-10-11 (from ops-base commit abc123)
- Fixed: Matrix registration token validation
- Added: WhatsApp bridge reconnection logic
- Security: Updated sops-nix to v0.16.0
6. Commit with tag:
git commit -m "Sync improvements from ops-base (2025-10-11)"
git tag "sync-20251011-abc123"
git push --tags
# sync-log.md format:
# Sync Log: ops-base → nixos-matrix-platform-template
## Sync 2025-10-11 (ops-base: abc123)
**Changes**:
- [BUGFIX] Matrix registration token validation
- [FEATURE] WhatsApp bridge reconnection
- [SECURITY] sops-nix v0.16.0 upgrade
**Skipped**:
- Personal config changes in comm-talu-uno.nix
```
### Alternatives Considered
- **Automated sync via git subtree**: Rejected - sanitization can't be automated
- **Manual documentation only**: Rejected - easy to forget, no traceability
- **Separate tracking tool**: Rejected - over-engineered for quarterly cadence
### Quarterly Sync Schedule
- Q1 (January): Major sync after holiday break
- Q2 (April): Feature updates and spring cleaning
- Q3 (July): Mid-year maintenance
- Q4 (October): Pre-holiday stability sync
---
## Decision 5: Testing Strategy
### Decision
**Build validation + selective VPS integration testing** (Phase 3 of RFC)
### Rationale
1. **Cost-effective**: Full VPS test only at major milestones
2. **Fast feedback**: nix flake check catches 90% of issues instantly
3. **Real validation**: At least one VPS deployment before v1.0 publication
4. **Community testing**: Beta testers provide diverse environment testing
5. **Risk management**: Balances thoroughness with time/cost
### Implementation
```
# Testing levels:
1. Every commit (CI):
- nix flake check (all configs)
- gitleaks scan
- Build example-vps.nix
- Build example-dev.nix
2. Before PR merge:
- All CI checks pass
- Manual review of sanitization
- Documentation accuracy check
3. Before v1.0 publication (Phase 3):
- Deploy example-vps.nix to fresh Vultr VPS
- Deploy example-dev.nix to fresh Vultr VPS
- Test all user stories end-to-end
- Verify Matrix server responds
- Test bridge setup guides
- Validate secrets management workflow
- Community beta testing (3-5 testers)
4. Post-publication:
- Monitor GitHub issues for deployment problems
- Track success metrics (SC-007, SC-008)
```
### VPS Test Checklist (Phase 3)
- [ ] Fresh NixOS VPS provisioned
- [ ] Clone template repository
- [ ] Follow getting-started.md (time it - should be <30 min)
- [ ] Customize example-vps.nix with test domain
- [ ] Deploy with nixos-rebuild
- [ ] Verify Matrix API responds (curl /_matrix/client/versions)
- [ ] Create test user with registration token
- [ ] Test Element Web login
- [ ] Follow slack-setup.md (if testing bridges)
- [ ] Verify CI runs on sample PR
- [ ] Document any issues or unclear docs
### Alternatives Considered
- **No integration testing**: Rejected - too risky for v1.0 publication
- **Automated VPS tests**: Deferred to v1.1 - complex setup, manual adequate for v1.0
- **Continuous VPS testing**: Rejected - expensive, unnecessary for template
---
## Decision 6: Repository Initialization Approach
### Decision
**Manual repository creation** on GitHub with direct file commits (not git-filter-repo)
### Rationale
1. **Clean history**: Fresh git init ensures no ops-base history
2. **Safety**: Manual process allows review at each step
3. **Simplicity**: Direct commits easier than git-filter-repo for one-time extraction
4. **Transparency**: Clear commit history shows sanitization process
### Implementation
```bash
# Repository creation workflow:
1. Create empty GitHub repo: nixos-matrix-platform-template
2. Clone to local machine
3. Copy sanitized files from staging directory
4. Review each file before adding
5. Create initial commit structure:
- Commit 1: Add README, LICENSE, .gitignore
- Commit 2: Add modules/
- Commit 3: Add configurations/
- Commit 4: Add docs/
- Commit 5: Add .github/workflows/
- Commit 6: Add examples/ and scripts/
6. Run final validation
7. Push to GitHub
8. Enable GitHub Discussions
9. Add repository description and tags
```
### No git-filter-repo
- Not needed - we're creating fresh repo, not rewriting history
- ops-base history stays in ops-base
- Template has clean, purposeful commit history
---
## Technology Stack Summary
### Core Technologies
- **Nix/NixOS**: 24.05+ (pinned via flake.lock)
- **nixpkgs**: Pinned to tested commit for reproducibility
- **sops-nix**: v0.15.0+ (secrets management)
- **age**: Latest (encryption backend for sops-nix)
### Validation & Security
- **gitleaks**: v8.18.0+ (secret scanning)
- **nix flake check**: Built-in Nix validation
### CI/CD
- **GitHub Actions**: Native CI/CD platform
- **cachix/install-nix-action@v25**: Nix installation for CI
- **gitleaks/gitleaks-action@v2**: Secret scanning action
### Development Tools
- **Bash**: 5.x (sanitization/sync scripts)
- **git**: 2.x (version control, tagging)
- **SSH**: For VPS deployment testing
### Services (Matrix Platform - in template)
- **matrix-continuwuity**: Matrix homeserver (from nixpkgs-unstable)
- **mautrix-slack**: Slack bridge
- **mautrix-whatsapp**: WhatsApp bridge
- **mautrix-gmessages**: Google Messages bridge
- **forgejo**: Git service
- **nginx**: Reverse proxy
- **postgresql**: Database for bridges/Forgejo
- **fail2ban**: Intrusion prevention
- **sops**: Secrets encryption CLI
---
## Best Practices Applied
### From NixOS Community
1. **Pinned dependencies**: Use flake.lock for reproducibility
2. **Module options**: Provide configurable options with sensible defaults
3. **Security hardening**: Apply systemd security features
4. **Documentation**: Comprehensive examples and guides
### From Infrastructure-as-Code
1. **Immutability**: Fresh git history, no rewrites
2. **Validation**: Multiple layers (syntax, build, secrets, integration)
3. **Idempotency**: All scripts can be run multiple times safely
4. **Auditability**: Clear commit messages, sync logs, checklists
### From Open Source Projects
1. **Governance files**: CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT
2. **Issue templates**: Structured bug reports and feature requests
3. **CI/CD**: Automated checks on every PR
4. **Semantic versioning**: v1.0.0 for initial stable release
---
## Risk Mitigations
### Secret Leakage (Critical Risk)
- **Mitigation 1**: Automated gitleaks scan (CI + local)
- **Mitigation 2**: Manual review checklist
- **Mitigation 3**: Fresh git history (no ops-base commits)
- **Mitigation 4**: Community beta review before publication
- **Residual Risk**: Low (multi-layer validation)
### Template Divergence (Medium Risk)
- **Mitigation 1**: Documented sync workflow (scripts/sync-to-template.sh)
- **Mitigation 2**: Quarterly calendar reminders
- **Mitigation 3**: Git tags + sync-log.md for tracking
- **Mitigation 4**: RFC-validated process
- **Residual Risk**: Medium (requires discipline)
### Breaking Dependencies (Medium Risk)
- **Mitigation 1**: Pinned nixpkgs version
- **Mitigation 2**: CI tests on every commit
- **Mitigation 3**: Integration testing before major releases
- **Mitigation 4**: Version compatibility matrix in README
- **Residual Risk**: Low (pinning prevents surprises)
### Poor Documentation (Medium Risk)
- **Mitigation 1**: Extract from 300KB+ tested worklogs
- **Mitigation 2**: Community beta testing for clarity
- **Mitigation 3**: User story acceptance criteria
- **Mitigation 4**: Quick start guide (5-minute target)
- **Residual Risk**: Low (comprehensive extraction + validation)
---
## Success Metrics Tracking
### How to Measure (post-publication)
- **SC-001** (30 min deployment): Time beta testers during Phase 3
- **SC-002** (builds pass): CI badge in README, track failures
- **SC-003** (zero secrets): gitleaks CI status, manual audits
- **SC-004** (8 modules extracted): Checklist of modules present and building - matrix-continuwuity, mautrix-slack, mautrix-whatsapp, mautrix-gmessages, dev-services, fail2ban, ssh-hardening, matrix-secrets
- **SC-005** (documentation complete): Checklist of required docs present - getting-started.md, architecture.md, secrets-management.md, slack-setup.md, whatsapp-setup.md, gmessages-setup.md, config-generation.md, admin-room-setup.md
- **SC-006** (CI runs): GitHub Actions badge, monitor runs
- **SC-007** (10 stars in 3 months): GitHub stars count
- **SC-008** (3 issues/PRs): GitHub insights
- **SC-009** (zero incidents): Monitor issues, no secret reports
- **SC-010** (quarterly sync): Track sync-log.md entries
---
## Open Questions Resolved
All open questions from spec were marked "None - resolved in RFC". Additional implementation questions resolved here:
1. **Q: Should we use pre-commit hooks?**
- A: Yes, but optional for users. Include .pre-commit-config.yaml example
2. **Q: What NixOS version to target?**
- A: 24.05+ (current stable), test on both stable and unstable
3. **Q: Should we include Cachix in CI?**
- A: Not for v1.0 (added complexity), consider for v1.1 if builds slow
4. **Q: How to handle user questions/support?**
- A: GitHub Discussions for Q&A, Issues for bugs only (per CONTRIBUTING.md)
5. **Q: Should we create a Matrix room for support?**
- A: Yes, mentioned in README (#nixos-matrix-template:matrix.org) - dogfooding
---
## Next Steps
1. ✅ Research completed - all decisions documented
2. → Proceed to Phase 1: Design & Contracts
- Create data-model.md (entities, relationships)
- Create contracts/ (sanitization rules, CI contracts)
- Create quickstart.md (developer onboarding)
- Update agent context (.specify/memory/AGENT_FILE.md)

214
specs/001-extract-matrix-platform/spec.md Normal file
View file

@ -0,0 +1,214 @@
# Feature Specification: Extract Matrix Platform Modules for ops-jrz1 Server
**Feature Branch**: `001-extract-matrix-platform`
**Created**: 2025-10-11
**Status**: Draft
**Input**: User description: "Extract Matrix platform modules from ops-base to configure ops-jrz1 dev/test server in this repository"
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Deploy Matrix Platform to ops-jrz1 Server (Priority: P1)
Deploy Matrix homeserver with bridges to the ops-jrz1 dev/test server using extracted and sanitized modules from this repository.
**Why this priority**: This is the primary deliverable - a working Matrix platform on ops-jrz1 using production-tested patterns from ops-base.
**Independent Test**: Can be fully tested by: (1) customizing configuration for ops-jrz1, (2) following deployment guide, (3) deploying to server, (4) verifying Matrix responds and user registration works. Delivers a working Matrix homeserver.
**Acceptance Scenarios**:
1. **Given** a developer with a VPS and domain name, **When** they follow the quick start guide (5 minutes), **Then** they have a clear understanding of next steps and requirements
2. **Given** the developer has customized the example configuration, **When** they run the deployment command, **Then** the Matrix homeserver starts successfully and responds to API requests
3. **Given** the Matrix homeserver is running, **When** the developer follows the bridge setup guide, **Then** they can add Slack/WhatsApp/Google Messages bridges to their deployment
---
### User Story 2 - Extract and Sanitize Modules from ops-base (Priority: P1)
Extract Matrix modules from ops-base, sanitize personal information (domains, IPs, secrets), and place them in this repository for ops-jrz1 server configuration.
**Why this priority**: This is foundational - must extract and sanitize modules before we can configure and deploy the server.
**Independent Test**: Can be tested by: (1) running sanitization scripts on ops-base modules, (2) verifying gitleaks finds no secrets, (3) verifying no personal domains/IPs remain, (4) building configurations successfully. Delivers sanitized modules ready for deployment.
**Acceptance Scenarios**:
1. **Given** ops-base contains production modules with personal config, **When** sanitization process runs, **Then** all personal domains (clarun.xyz, talu.uno) are replaced with example.com variants
2. **Given** modules contain personal IP addresses, **When** sanitization completes, **Then** all IPs are replaced with RFC 1918 private ranges or TEST-NET-3 public examples
3. **Given** the sanitized repository, **When** gitleaks secret scanning runs, **Then** no secrets, tokens, or sensitive data are detected
4. **Given** sanitized files, **When** nix flake check runs, **Then** all configurations build successfully with no syntax errors
---
### User Story 3 - Enable Community Contributions (Priority: P3 - Deferred)
**Status**: Deferred until public publication. Add governance files (CONTRIBUTING.md, SECURITY.md) and community features when ready to share publicly.
**Why deferred**: Not needed for internal dev/test server. Will implement before public sharing.
**Acceptance Scenarios**:
1. **Given** a developer wants to contribute, **When** they read CONTRIBUTING.md, **Then** they understand the process, testing requirements, and code standards
2. **Given** a developer submits a pull request, **When** they push their branch, **Then** pre-push hooks validate (nix flake check, gitleaks, build tests) before changes reach remote
3. **Given** a valid pull request passes CI, **When** maintainers review it, **Then** they can merge or request changes based on clear contribution guidelines
---
### User Story 4 - Sync Improvements from ops-base (Priority: P2)
Create workflow for syncing future improvements from ops-base back to this repository as modules evolve.
**Why this priority**: Useful for ongoing maintenance as production environment improves, but not critical for initial deployment.
**Acceptance Scenarios**:
1. **Given** improvements exist in ops-base modules, **When** maintainer runs sync workflow script, **Then** the script identifies changes and generates sanitized diff for review
2. **Given** sanitized changes ready to apply, **When** maintainer applies them to template, **Then** automated tests (nix flake check, gitleaks) verify no secrets leaked and builds pass
3. **Given** synced changes are validated, **When** maintainer commits and pushes, **Then** git hooks validate successfully and template remains secure
---
### User Story 5 - Developer Learns Matrix Bridge Patterns from Documentation (Priority: P3)
A developer wants to understand how to implement specific patterns (like Socket Mode authentication, gmessages-style config generation, or admin room setup) that are documented in the template's pattern guides.
**Why this priority**: Educational value adds community benefit but is not essential for basic deployment. Nice-to-have for initial launch, can be improved iteratively.
**Independent Test**: Can be tested by: (1) reading pattern documentation (e.g., Socket Mode setup), (2) following the steps in the guide, (3) verifying the pattern works as documented. Delivers knowledge transfer value.
**Acceptance Scenarios**:
1. **Given** a developer implementing Slack bridge, **When** they read docs/bridges/slack-setup.md, **Then** they understand Socket Mode vs webhooks and have a checklist of OAuth scopes needed
2. **Given** a developer encounters gmessages config generation pattern, **When** they read docs/patterns/config-generation.md, **Then** they understand why runtime regeneration is used and can apply the pattern to other bridges
3. **Given** a developer using Conduwuit, **When** they read docs/patterns/admin-room-setup.md, **Then** they can successfully register appservices via admin room commands
---
### Edge Cases
- What happens when a user tries to deploy without setting up sops-nix secrets management first?
- How does the template handle users on different NixOS versions (stable vs unstable)?
- What if a user deploys to ARM architecture instead of x86_64?
- How does sanitization handle new personal references added after initial publication?
- What happens if upstream bridge packages introduce breaking changes?
- How does the sync workflow prevent accidental secret leakage during updates?
## Requirements *(mandatory)*
### Functional Requirements
**Repository Structure & Sanitization:**
- **FR-001**: Repository MUST contain sanitized NixOS modules for Matrix homeserver (Continuwuity), mautrix bridges (Slack, WhatsApp, Google Messages), and security hardening
- **FR-002**: All personal domains MUST be replaced with generic examples or ops-jrz1-specific values (clarun.xyz → example.com, talu.uno → ops-jrz1 domain)
- **FR-003**: All personal IP addresses MUST be replaced with RFC 1918 private ranges (10.0.0.x) or ops-jrz1-specific addresses
- **FR-004**: All secrets MUST be removed from extracted code and managed via sops-nix
- **FR-005**: All personal paths MUST be sanitized (/home/dan → appropriate paths)
- **FR-006**: Extracted modules MUST NOT contain encrypted secrets or personal debugging logs from ops-base
- **FR-007**: Repository MUST include ops-jrz1 server configuration that builds successfully
**Documentation:**
- **FR-008**: Repository MUST include README with architecture overview and deployment guide
- **FR-009**: Repository SHOULD include deployment documentation for ops-jrz1 server
- **FR-010**: Repository SHOULD include bridge setup notes extracted from worklogs (for reference)
- **FR-011**: Repository SHOULD include pattern documentation extracted from worklogs (for reference)
- **FR-012**: Repository MUST include secrets-management documentation for sops-nix
- **FR-013**: Documentation MUST NOT contain personal infrastructure details from ops-base
**Security & Validation:**
- **FR-014**: Repository MUST pass gitleaks secret scanning with zero findings
- **FR-015**: Configuration MUST pass `nix flake check` validation
- **FR-016**: Repository SHOULD include git pre-commit and pre-push hooks for validation
- **FR-017**: Deferred - CI workflow not needed for internal dev server
- **FR-018**: Deferred - SECURITY.md for future public sharing
**Community & Governance:**
- **FR-019**: Deferred - CONTRIBUTING.md for future public sharing
- **FR-020**: Deferred - Issue templates for future public sharing
- **FR-021**: Repository SHOULD include LICENSE file for future sharing
- **FR-022**: Deferred - Community features for future public sharing
**Sync Workflow:**
- **FR-023**: Repository SHOULD document workflow for future syncs from ops-base
- **FR-024**: Repository SHOULD include helper scripts for identifying and sanitizing changes
- **FR-025**: Sync workflow SHOULD include validation steps (build check, gitleaks scan)
- **FR-026**: Deferred - Quarterly reminders for ongoing maintenance
**Testing & Deployment:**
- **FR-027**: Configuration MUST be tested by deploying to ops-jrz1 server
- **FR-028**: Configuration targets x86_64-linux architecture
- **FR-029**: All modules MUST build against pinned nixpkgs version for reproducibility
### Key Entities *(include if feature involves data)*
- **Module**: A reusable NixOS module file (e.g., matrix-continuwuity.nix, mautrix-slack.nix) containing service configuration and systemd units
- **Configuration**: An example deployment configuration file (e.g., example-vps.nix) that imports modules and sets options
- **Secret**: Sensitive data (tokens, passwords, keys) managed via sops-nix encryption, stored in secrets/secrets.yaml
- **Pattern Document**: Extracted architectural knowledge from worklogs explaining proven implementation approaches
- **Bridge Setup Guide**: Step-by-step documentation for configuring specific Matrix bridges with authentication and registration
- **Sanitization Rule**: A find/replace or validation rule that ensures personal information is removed (domain, IP, path, secret patterns)
- **Sync Checkpoint**: A record of what changes have been synced from ops-base to template at a specific point in time
## Success Criteria *(mandatory)*
### Measurable Outcomes
- **SC-001**: Configuration can be deployed to ops-jrz1 server and Matrix homeserver responds within 30 minutes
- **SC-002**: Configuration builds successfully with `nix flake check` (zero errors)
- **SC-003**: gitleaks secret scanning returns zero findings across entire repository
- **SC-004**: All target modules extracted and building: matrix-continuwuity, mautrix-slack, mautrix-whatsapp, mautrix-gmessages, security/fail2ban, security/ssh-hardening (6+ modules total)
- **SC-005**: Core documentation complete: README, deployment guide, secrets-management docs
- **SC-006**: Deferred - Git hooks for future enforcement
- **SC-007**: Deferred - Community metrics for future public sharing
- **SC-008**: Deferred - Community engagement for future public sharing
- **SC-009**: Zero security incidents (no secret leakage from ops-base extraction)
- **SC-010**: Deferred - Sync workflow for ongoing maintenance
## Assumptions *(mandatory)*
- ops-jrz1 is a dev/test server (not production - no 99.9999% uptime requirement)
- Maintainer has basic familiarity with NixOS and Nix flakes
- ops-jrz1 server exists or will be provisioned for deployment
- Domain name and DNS available for ops-jrz1 server
- SSH access to ops-jrz1 server available
- ops-base repository contains working Matrix modules to extract
- ops-base repository may contain worklogs with useful pattern documentation
- Maintainer has access to ops-base (private) repository
- gitleaks tool available for secret scanning
- NixOS provides necessary packages (matrix-continuwuity, mautrix bridges)
## Out of Scope *(include if needed to clarify boundaries)*
- Public template repository (deferred for future)
- Community contribution features (deferred for future)
- Rewriting git history in ops-base
- Automated sync from ops-base (manual extraction for now)
- Support for platforms other than NixOS
- Graphical configuration UI
- Hosting services or managed deployments
- Non-Matrix services beyond extracted modules
- Matrix clients or frontend components
- Custom bridge development
- Multi-host deployments (single-host for ops-jrz1)
- Windows or macOS deployment targets
- Production monitoring/observability (can be added later)
## Dependencies *(include if feature relies on external factors)*
- **NixOS/nixpkgs**: Requires packages for matrix-continuwuity, mautrix-slack, mautrix-whatsapp, mautrix-gmessages, forgejo
- **sops-nix**: Required for secrets management, must be compatible with current NixOS version
- **Git hosting platform**: Required for hosting repository (Forgejo for development, GitHub/tangl.sh for public publication)
- **gitleaks**: Required for automated secret scanning in CI and locally
- **age encryption tool**: Required for sops-nix secret encryption
- **ops-base repository**: Source of modules and documentation to be extracted
- **Nix flake system**: Template uses flakes for dependency management and configuration
- **Let's Encrypt / ACME**: Assumed for TLS certificate generation (users must configure)
## Open Questions *(include if there are unresolved decisions)*
None - all critical decisions were resolved in the RFC consensus validation process.

531
specs/001-extract-matrix-platform/tasks.md Normal file
View file

@ -0,0 +1,531 @@
# Tasks: Extract Matrix Platform Modules for ops-jrz1 Server
**Input**: Design documents from `/specs/001-extract-matrix-platform/`
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. This is a repository extraction project, so tasks focus on extracting, sanitizing, documenting, and publishing rather than traditional software development.
## Format: `[ID] [P?] [Story] Description`
- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (US1-US5)
- Include exact file paths in descriptions
## Path Conventions
This is a SINGLE repository project:
- **ops-jrz1** (this repo): Planning docs + extracted modules + server configuration
All work happens in this repository:
- **specs/001-extract-matrix-platform/**: Planning and design docs (speckit workflow)
- **staging/**: Temporary workspace for extraction from ops-base
- **modules/**: Sanitized Matrix modules (extracted from ops-base)
- **hosts/ops-jrz1.nix**: Server-specific configuration
- **flake.nix**: Server flake configuration
- **configuration.nix**: Main server configuration
## Repository Architecture
**Current Phase**: Extract modules from ops-base, sanitize, configure ops-jrz1 dev/test server
**Future (Deferred)**: Public template sharing when ready
---
## Phase 1: Setup (Shared Infrastructure)
**Purpose**: Initialize workspace and create basic repository structure
- [x] T001 Create staging directory structure in ~/proj/ops-jrz1/staging/{modules,configurations,docs}
- [x] T002 (OBSOLETE - single repo) Create Forgejo repository - not needed, using ops-jrz1
- [x] T003 (OBSOLETE - single repo) Clone template locally - not needed, using ops-jrz1
- [x] T004 Create directory structure in ops-jrz1 repo root: modules/, hosts/, docs/, secrets/, scripts/ (per plan.md structure)
- [x] T004a Create hosts/ops-jrz1.nix with dev/test server-specific configuration
- [x] T004b Create flake.nix skeleton referencing ops-jrz1 host (will be expanded in T032)
- [x] T004c Create configuration.nix importing ops-jrz1 host module
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Core scripts and contracts that MUST be complete before ANY user story can be implemented
**⚠️ CRITICAL**: No extraction/sanitization work can begin until these tools are ready
- [x] T005 Create scripts/sanitize-files.sh based on contracts/sanitization-rules.yaml (applies all 22 sanitization rules)
- [x] T006 [P] Create scripts/validate-sanitization.sh (runs gitleaks + pattern checks from contracts)
- [x] T007 [P] Create .pre-commit-config.yaml with pre-commit and pre-push hooks (gitleaks + nix flake check + build validation) - PRIMARY VALIDATION
- [x] T008 [P] Create git hooks wrapper scripts in scripts/hooks/ (called by pre-commit framework)
- [x] T009 Create initial .gitignore for ops-jrz1 repo (result, result-*, secrets/*.yaml except examples)
- [x] T010 Create initial README.md in ops-jrz1 repo (work-in-progress status, planned features)
- [x] T011 [P] Create LICENSE file in ops-jrz1 repo (MIT license text)
**Checkpoint**: Foundation ready - extraction and sanitization can now begin
---
## Phase 3: User Story 2 - Sanitize and Publish Template (Priority: P1) 🎯 FOUNDATIONAL
**Goal**: Extract modules from ops-base, sanitize all personal information, and create clean publishable repository
**Why First**: This is the foundational story - must complete before US1 (deployment) can be tested. US2 creates the artifact that US1 uses.
**Independent Test**: Run sanitization scripts → verify gitleaks finds zero secrets → verify no personal domains/IPs → build all example configs successfully
### Module Extraction (US2)
- [ ] T012 [P] [US2] Copy modules/matrix-continuwuity.nix from ops-base to staging/modules/
- [ ] T013 [P] [US2] Copy modules/mautrix-slack.nix from ops-base to staging/modules/
- [ ] T014 [P] [US2] Copy modules/mautrix-whatsapp.nix from ops-base to staging/modules/
- [ ] T015 [P] [US2] Copy modules/mautrix-gmessages.nix from ops-base to staging/modules/
- [ ] T016 [P] [US2] Copy modules/dev-services.nix from ops-base to staging/modules/
- [ ] T017 [P] [US2] Copy modules/security/fail2ban.nix from ops-base to staging/modules/security/
- [ ] T018 [P] [US2] Copy modules/security/ssh-hardening.nix from ops-base to staging/modules/security/
- [ ] T019 [P] [US2] Copy modules/matrix-secrets/default.nix from ops-base to staging/modules/matrix-secrets/
### Configuration Extraction (US2)
- [ ] T020 [P] [US2] Copy configurations/vultr-dev.nix from ops-base to staging/configurations/example-vps.nix
- [ ] T021 [P] [US2] Copy configurations/dev-vps.nix from ops-base to staging/configurations/example-dev.nix
### Sanitization (US2)
- [ ] T022 [US2] Run scripts/sanitize-files.sh on staging/modules/ → output to modules/
- [ ] T023 [US2] Run scripts/sanitize-files.sh on staging/configurations/ → output to hosts/
- [ ] T024 [US2] Manual review of all .nix files for personal references in comments (checklist: comments, docs, inline notes)
- [ ] T025 [US2] Add REPLACE_ME comments to domain/workspace/secret fields in sanitized files
### Validation (US2)
- [ ] T026 [US2] Run scripts/validate-sanitization.sh on modules/ (expect: zero personal domains/IPs/paths)
- [ ] T027 [US2] Run scripts/validate-sanitization.sh on hosts/ (expect: zero personal domains/IPs/paths)
- [ ] T028 [US2] Run gitleaks detect --no-git --source . (expect: zero secrets found)
### Example Files (US2)
- [ ] T029 [P] [US2] Create examples/secrets.yaml.example with sops-nix template structure
- [ ] T030 [P] [US2] Create examples/.sops.yaml.example with age key placeholder
- [ ] T031 [P] [US2] Create examples/minimal-matrix.nix as simplest working configuration
### Flake Configuration (US2)
- [ ] T032 [US2] Create flake.nix in ops-jrz1 repo (imports: nixpkgs, sops-nix; outputs: ops-jrz1 nixosConfiguration)
- [ ] T033 [US2] Run nix flake lock in ops-jrz1 repo to generate flake.lock
- [ ] T034 [US2] Run nix flake check in ops-jrz1 repo (expect: all checks pass)
- [ ] T035 [US2] Run nix build .#nixosConfigurations.ops-jrz1.config.system.build.toplevel (expect: builds successfully)
- [ ] T036 (OBSOLETE - single config) Run nix build .#nixosConfigurations.example-dev.config.system.build.toplevel (expect: builds successfully)
### Initial Commit (US2)
- [ ] T037 [US2] Commit sanitized modules to ops-jrz1 repo: "Add sanitized NixOS modules for Matrix platform"
- [ ] T038 [US2] Commit ops-jrz1 server configuration: "Add ops-jrz1 server configuration"
- [ ] T039 (OBSOLETE - single repo) Push to Forgejo (work stays in ops-jrz1 branch)
**Checkpoint**: User Story 2 complete - sanitized modules in ops-jrz1 repo, builds pass, zero secrets detected
---
## Phase 4: User Story 5 - Documentation Extraction (Priority: P3)
**Goal**: Extract pattern documentation from worklogs and create comprehensive guides
**Why Before US1**: Documentation must exist for US1 (deployment) testing. Developers need guides to deploy.
**Independent Test**: Read each doc → verify technical accuracy → verify no personal infrastructure references → verify examples use generic domains/IPs
### Pattern Documentation (US5)
- [ ] T040 [P] [US5] Extract docs/patterns/config-generation.md from mautrix-slack-bridge-implementation-gmessages-pattern.org worklog
- [ ] T041 [P] [US5] Extract docs/patterns/admin-room-setup.md from conduwuit-admin-room-discovery-password-reset.org worklog
- [ ] T042 [P] [US5] Sanitize docs/patterns/*.md for personal infrastructure references (check for clarun.xyz, talu.uno, personal IPs)
### Bridge Setup Guides (US5)
- [ ] T043 [P] [US5] Extract docs/bridges/slack-setup.md from mautrix-slack-socket-mode-oauth-scopes-blocker.org worklog (Socket Mode, OAuth scopes)
- [ ] T044 [P] [US5] Create docs/bridges/whatsapp-setup.md from module configuration and QR pairing pattern (authentication flow, troubleshooting)
- [ ] T045 [P] [US5] Create docs/bridges/gmessages-setup.md from module configuration and pairing process (prerequisites, common issues)
- [ ] T046 [US5] Sanitize docs/bridges/*.md for personal infrastructure references
### Core Documentation (US5)
- [ ] T047 [P] [US5] Extract docs/secrets-management.md from sops-nix-secrets-management-rfc.md (sops-nix setup, age keys, workflow)
- [ ] T048 [P] [US5] Create docs/architecture.md from RFC and worklogs (system design, module relationships, deployment model)
- [ ] T049 [P] [US5] Create docs/getting-started.md with 5-minute quickstart (prerequisites, customization, deployment steps)
- [ ] T050 [P] [US5] Create docs/deployment.md with detailed deployment guide (VPS setup, DNS, TLS, troubleshooting)
- [ ] T051 [US5] Sanitize docs/*.md for personal infrastructure references
### Validation (US5)
- [ ] T052 [US5] Review all documentation for technical accuracy against actual module code
- [ ] T053 [US5] Verify all code examples in docs use example.com/10.0.0.x/generic values
- [ ] T054 [US5] Verify all docs link to correct files and sections (no broken internal links)
### Commit Documentation (US5)
- [ ] T055 [US5] Commit documentation to ops-jrz1 repo: "Add comprehensive documentation extracted from worklogs"
- [ ] T056 (OBSOLETE - single repo) Push documentation to Forgejo (work stays in ops-jrz1 branch)
**Checkpoint**: User Story 5 complete - all 8 required documentation sections present and sanitized
---
## Phase 5: User Story 3 - Community Governance (Priority: P3 - OPTIONAL/DEFERRED)
**Goal**: Add governance files (CONTRIBUTING.md, SECURITY.md) and CI/CD to enable community contributions
**Status**: Per spec.md US3 is P3-DEFERRED for future public sharing. Can be implemented later when ready for community contributions.
**Independent Test**: Fork repo → make sample change → verify CI runs → verify contribution guidelines clear
### Governance Files (US3)
- [ ] T057 [P] [US3] Create CONTRIBUTING.md with contribution guidelines, testing requirements, PR process
- [ ] T058 [P] [US3] Create SECURITY.md with vulnerability disclosure process, supported versions, response times
- [ ] T059 [P] [US3] Create .github/ISSUE_TEMPLATE/bug_report.yml with structured bug report template
- [ ] T060 [P] [US3] Create .github/ISSUE_TEMPLATE/feature_request.yml with feature request template
- [ ] T061 [P] [US3] Update README.md with community links, contribution section, code of conduct reference
### Git Hooks Validation (US3)
- [ ] T062 [US3] Install pre-commit framework in ops-jrz1 repo: pre-commit install
- [ ] T063 [US3] Test pre-commit hook blocks bad commit (intentionally add clarun.xyz, verify hook rejects)
- [ ] T064 [US3] Test pre-push hook validates builds (make change, verify nix flake check runs before push)
- [ ] T065 [US3] Verify hooks pass with valid changes (fix typo, confirm commit/push succeeds)
### Repository Settings (US3) - Forgejo
- [ ] T066 [US3] Add repository description in Forgejo: "Production-ready NixOS modules for Matrix homeserver with bridges"
- [ ] T067 [US3] Configure repository topics in Forgejo: nixos, matrix, continuwuity, mautrix, homeserver, nix-flakes
- [ ] T068 [US3] Set repository visibility to private (development phase)
- [ ] T069 [DEFER] Enable community features when publishing to public platform (Phase 8)
### Commit Governance (US3)
- [ ] T070 [US3] Commit governance files to ops-jrz1 repo: "Add community governance and contribution guidelines"
- [ ] T071 (OBSOLETE - single repo) Push governance files to Forgejo (work stays in ops-jrz1 branch)
**Checkpoint**: User Story 3 complete - community can fork, contribute, and submit PRs with git hooks validation
---
## Phase 6: User Story 4 - Sync Workflow (Priority: P2)
**Goal**: Create documented workflow and scripts for syncing future improvements from ops-base to template
**Independent Test**: Identify sample ops-base changes → run sync script → verify changes sanitized → verify no secrets leaked → builds pass
### Sync Scripts (US4)
- [ ] T072 [US4] Create scripts/sync-to-template.sh based on research.md sync workflow (identify changes, sanitize, validate)
- [ ] T073 [US4] Create sync-log.md in ops-jrz1 repo with initial publication entry (date, ops-base commit, modules list)
- [ ] T074 [US4] Add quarterly sync schedule to maintainer calendar (January, April, July, October reminders)
### Sync Documentation (US4)
- [ ] T075 [US4] Document sync workflow in ops-jrz1 repo README (when to sync, how to use scripts, validation steps)
- [ ] T076 [US4] Create sync testing checklist based on contracts/sanitization-rules.yaml (validation steps, expected results)
### Sync Testing (US4)
- [ ] T077 [US4] Test sync workflow with mock change in ops-base (add comment to module, sync to template, verify sanitized)
- [ ] T078 [US4] Verify sync validation catches personal references (intentionally add clarun.xyz, verify script rejects)
- [ ] T079 [US4] Verify sync creates git tag and sync-log.md entry correctly
### Commit Sync Workflow (US4)
- [ ] T080 [US4] Commit sync scripts and documentation to ops-jrz1 repo: "Add sync workflow for ongoing maintenance"
- [ ] T081 (OBSOLETE - single repo) Push sync workflow to Forgejo (work stays in ops-jrz1 branch)
**Checkpoint**: User Story 4 complete - maintainer can sync improvements from ops-base quarterly
---
## Phase 7: User Story 1 - Deploy to ops-jrz1 Server (Priority: P1) 🎯 VALIDATION
**Goal**: Deploy Matrix platform to ops-jrz1 dev/test server using extracted and sanitized modules
**Why Last**: Requires sanitized modules (US2) and documentation (US5) to be complete before deployment
**Independent Test**: Customize configuration for ops-jrz1 → deploy to server → verify Matrix responds → verify bridges work
### ops-jrz1 Server Provisioning (US1)
- [ ] T082 [US1] Verify ops-jrz1 server exists and is accessible via SSH (x86_64-linux, NixOS 24.05+)
- [ ] T083 [US1] Configure DNS for ops-jrz1 domain pointing to server IP
- [ ] T084 [US1] SSH to ops-jrz1 and verify NixOS version and nix flake support
### Deployment Following Docs (US1)
- [ ] T085 [US1] Verify ops-jrz1 repo is up to date on branch 001-extract-matrix-platform
- [ ] T086 [US1] Follow docs/getting-started.md step-by-step, time the process (target: <30 minutes)
- [ ] T087 [US1] Customize hosts/ops-jrz1.nix with server domain and settings
- [ ] T088 [US1] Generate age key on ops-jrz1 server: ssh-to-age < /etc/ssh/ssh_host_ed25519_key.pub
- [ ] T089 [US1] Create secrets/secrets.yaml with ops-jrz1 values (matrix registration token, acme email)
- [ ] T090 [US1] Encrypt secrets with sops: sops -e -i secrets/secrets.yaml
- [ ] T091 [US1] Deploy to ops-jrz1: nixos-rebuild switch --flake .#ops-jrz1 --target-host root@<ops-jrz1-ip>
### Functional Validation (US1)
- [ ] T092 [US1] Verify Matrix homeserver responds: curl https://<ops-jrz1-domain>/_matrix/client/versions (expect: JSON response)
- [ ] T093 [US1] Verify .well-known endpoints: curl https://<ops-jrz1-domain>/.well-known/matrix/server (expect: JSON)
- [ ] T094 [US1] Create test user via registration: use matrix registration token
- [ ] T095 [US1] Login to Element Web with test user credentials (verify authentication works)
- [ ] T096 [US1] Verify systemd services running: ssh root@ops-jrz1 systemctl status matrix-continuwuity
### Bridge Testing (US1)
- [ ] T097 [US1] Follow docs/bridges/slack-setup.md to configure Slack bridge (if testing bridges)
- [ ] T098 [US1] Verify bridge appservice registered with Matrix homeserver
- [ ] T099 [US1] Test bridge message flow (send test message, verify delivery)
### Issues and Documentation Updates (US1)
- [ ] T100 [US1] Document any unclear steps or issues encountered during deployment
- [ ] T101 [US1] Update docs/getting-started.md based on deployment experience (fix ambiguities, add troubleshooting)
- [ ] T102 [US1] Update docs/deployment.md with any missing steps or common issues discovered
### Timing and Metrics (US1)
- [ ] T103 [US1] Verify total deployment time from clone to working Matrix was <30 minutes (SC-001)
- [ ] T104 [US1] Record deployment experience notes for README improvement
**Checkpoint**: User Story 1 complete - ops-jrz1 server deployed with working Matrix homeserver in <30 minutes
---
## Phase 8: Polish & Cross-Cutting Concerns (Partial Deferral)
**Purpose**: Final improvements affecting multiple user stories, preparation for v1.0 publication
**Note**: Public release tasks (T119-T125) are DEFERRED per spec.md Out of Scope. Security validation and build checks remain in scope.
### README Expansion
- [ ] T105 [P] Expand README.md with ops-jrz1 server overview, Matrix platform features, deployment status
- [ ] T106 [P] Add license badge to README: ![License](https://img.shields.io/badge/license-MIT-blue.svg)
- [ ] T107 (DEFERRED) Add repository links to README (for future public template)
- [ ] T108 (DEFERRED) Add community contact info to README (for future public sharing)
### Final Security Validation
- [ ] T109 Run gitleaks on full ops-jrz1 repository (expect: zero findings) - final verification
- [ ] T110 Manual grep for all sensitive patterns: rg 'clarun|talu|192\.168\.1\.|45\.77|/home/dan' in sanitized modules/hosts/docs (expect: no matches)
- [ ] T111 Review git log for any accidentally committed secrets or personal info in branch 001-extract-matrix-platform
- [ ] T112 Verify no .sops.yaml with real age keys committed (only .sops.yaml.example if present)
### Build Validation
- [ ] T113 Run nix flake check (expect: all checks pass)
- [ ] T114 Build ops-jrz1 configuration: nix build .#nixosConfigurations.ops-jrz1 (expect: success)
- [ ] T115 (OBSOLETE - single config) Build example-dev configuration - not needed for single-repo ops-jrz1
### Module Checklist Verification (SC-004)
- [ ] T116 Verify all 6+ core modules present and building: matrix-continuwuity ✓, mautrix-slack ✓, mautrix-whatsapp ✓, mautrix-gmessages ✓, fail2ban ✓, ssh-hardening ✓, plus optional dev-services ✓ and matrix-secrets ✓
### Documentation Checklist Verification (SC-005)
- [ ] T117 Verify core documentation complete: README ✓, deployment guide ✓, secrets-management ✓, plus optional bridge/pattern docs: slack-setup.md ✓, whatsapp-setup.md ✓, gmessages-setup.md ✓, config-generation.md ✓, admin-room-setup.md ✓
### Release Preparation
- [ ] T118 Create v1.0.0 release tag: git tag v1.0.0 -m "Initial release - ops-jrz1 Matrix platform"
- [ ] T119 (DEFERRED) Create public repository (GitHub/tangl.sh) for template publication
- [ ] T120 (DEFERRED) Push sanitized template with tags to public repository
### Announcement Preparation (DEFERRED)
- [ ] T121 (DEFERRED) [P] Draft announcement post for Matrix.org community (#nix:nixos.org)
- [ ] T122 (DEFERRED) [P] Draft announcement post for NixOS Discourse
- [ ] T123 (DEFERRED) [P] Draft announcement post for Reddit r/NixOS
- [ ] T124 (DEFERRED) [P] Draft Show HN post for Hacker News
- [ ] T125 (DEFERRED) Publish announcements across all channels (coordinate timing)
---
## Dependencies & Execution Order
### Phase Dependencies
- **Phase 1 (Setup)**: No dependencies - can start immediately
- **Phase 2 (Foundational)**: Depends on Phase 1 (Setup) - BLOCKS all user stories
- **Phase 3 (US2 - Sanitize)**: Depends on Phase 2 (Foundational) - scripts must exist first
- **Phase 4 (US5 - Docs)**: Depends on Phase 3 (US2) - modules must be sanitized first
- **Phase 5 (US3 - Governance)**: Can start after Phase 2, parallel with US2/US5
- **Phase 6 (US4 - Sync)**: Can start after Phase 2, parallel with other stories
- **Phase 7 (US1 - Deployment)**: Depends on Phase 3, Phase 4, Phase 5 (needs complete template to test)
- **Phase 8 (Polish)**: Depends on all user stories complete
### User Story Dependencies
- **US2 (Sanitize/Publish)**: FOUNDATIONAL - no dependencies, enables all others
- **US5 (Documentation)**: Depends on US2 (modules must exist to document them)
- **US3 (Governance)**: Independent, can run parallel with US2/US5
- **US4 (Sync Workflow)**: Independent, can run parallel with US2/US5
- **US1 (Deployment)**: Depends on US2 + US5 + US3 (needs modules + docs + CI to test)
### Critical Path
```
Phase 1 (Setup)
↓
Phase 2 (Foundational - scripts/CI)
↓
Phase 3 (US2 - Extract & Sanitize Modules) ← CRITICAL PATH
↓
Phase 4 (US5 - Extract Documentation) ← CRITICAL PATH
↓
Phase 7 (US1 - VPS Deployment Test) ← CRITICAL PATH
↓
Phase 8 (Polish & Release)
```
**Parallel Opportunities**:
- Phase 5 (US3) and Phase 6 (US4) can run in parallel with Phase 3/4
- Within Phase 3: T012-T021 (module/config copies) all parallel
- Within Phase 4: T040-T051 (doc extraction) most are parallel
- Within Phase 8: Many polish tasks parallel (T105-T108, T121-T124)
### Within Each Phase
**Phase 3 (US2) order**:
1. Copy all modules/configs in parallel (T012-T021)
2. Run sanitization sequentially (T022-T023) - depends on copies
3. Manual review (T024-T025) - depends on sanitization
4. Validation (T026-T028) - depends on review
5. Create examples in parallel (T029-T031)
6. Flake config sequentially (T032-T036) - incremental dependencies
7. Commit (T037-T039)
**Phase 7 (US1) order**:
1. VPS provisioning (T082-T084)
2. Clone and customize sequentially (T085-T091) - follows docs
3. Functional validation (T092-T096)
4. Optional bridge testing (T097-T099)
5. Documentation improvements (T100-T102)
6. Metrics collection (T103-T104)
---
## Parallel Execution Examples
### Phase 2: Foundational Scripts
```bash
# All foundational scripts can be created in parallel:
Task: "Create scripts/sanitize-files.sh"
Task: "Create scripts/validate-sanitization.sh"
Task: "Create .github/workflows/ci.yml"
Task: "Create .pre-commit-config.yaml"
Task: "Create LICENSE file"
```
### Phase 3: Module Extraction (US2)
```bash
# All module copies can run in parallel:
Task: "Copy modules/matrix-continuwuity.nix"
Task: "Copy modules/mautrix-slack.nix"
Task: "Copy modules/mautrix-whatsapp.nix"
Task: "Copy modules/mautrix-gmessages.nix"
Task: "Copy modules/dev-services.nix"
Task: "Copy modules/security/fail2ban.nix"
Task: "Copy modules/security/ssh-hardening.nix"
Task: "Copy modules/matrix-secrets/default.nix"
Task: "Copy configurations/example-vps.nix"
Task: "Copy configurations/example-dev.nix"
```
### Phase 4: Documentation (US5)
```bash
# Pattern docs in parallel:
Task: "Extract docs/patterns/config-generation.md"
Task: "Extract docs/patterns/admin-room-setup.md"
# Bridge guides in parallel:
Task: "Extract docs/bridges/slack-setup.md"
Task: "Create docs/bridges/whatsapp-setup.md"
Task: "Create docs/bridges/gmessages-setup.md"
# Core docs in parallel:
Task: "Extract docs/secrets-management.md"
Task: "Create docs/architecture.md"
Task: "Create docs/getting-started.md"
Task: "Create docs/deployment.md"
```
---
## Implementation Strategy
### MVP First (US2 + US5 + US1)
1. Complete Phase 1: Setup (T001-T004)
2. Complete Phase 2: Foundational (T005-T011) - CRITICAL
3. Complete Phase 3: US2 Sanitize (T012-T039) - Extract modules
4. Complete Phase 4: US5 Documentation (T040-T056) - Add docs
5. Skip Phase 5-6 temporarily (governance/sync can wait)
6. Complete Phase 7: US1 Deployment Test (T082-T104) - VALIDATE
7. **STOP and EVALUATE**: Do we have a working template?
### Full v1.0 (All Stories)
1. Complete MVP (above)
2. Add Phase 5: US3 Governance (T057-T071) - Community contributions
3. Add Phase 6: US4 Sync Workflow (T072-T081) - Maintenance
4. Complete Phase 8: Polish (T105-T125) - Final touches & publication
### Incremental Delivery
1. **Week 1**: Setup + Foundational + Module Extraction (T001-T039) → Sanitized modules exist
2. **Week 2**: Documentation (T040-T056) → Comprehensive docs exist
3. **Week 3**: Deployment Testing (T082-T104) → Validated working template
4. **Week 4**: Governance + Sync + Polish (T057-T125) → v1.0 ready for publication
---
## Task Summary
**Total Tasks**: 125
- Phase 1 (Setup): 4 tasks
- Phase 2 (Foundational): 7 tasks (BLOCKING)
- Phase 3 (US2 - Sanitize): 28 tasks
- Phase 4 (US5 - Documentation): 17 tasks
- Phase 5 (US3 - Governance): 15 tasks
- Phase 6 (US4 - Sync): 10 tasks
- Phase 7 (US1 - Deployment): 23 tasks
- Phase 8 (Polish): 21 tasks
**By User Story**:
- US2 (Sanitize/Publish): 28 tasks - FOUNDATIONAL
- US5 (Documentation): 17 tasks
- US3 (Governance): 15 tasks
- US4 (Sync Workflow): 10 tasks
- US1 (Deployment Test): 23 tasks
- Shared (Setup/Foundational/Polish): 32 tasks
**Parallel Opportunities**: 45+ tasks marked [P] for parallel execution
**Independent Test Criteria**:
- US2: gitleaks zero findings + builds pass + no personal refs
- US5: docs complete + sanitized + technically accurate
- US3: fork + change + CI passes + guidelines clear
- US4: sync mock change + validate + no secrets leaked
- US1: clone + deploy + Matrix responds + <30 min
**Suggested MVP Scope**: US2 + US5 + US1 (73 tasks) - Delivers working template with docs, validated on VPS
---
## Notes
- This is a **repository extraction project**, not traditional software development
- Primary activity is copying, sanitizing, documenting, and validating
- Testing is manual validation (gitleaks, nix flake check, VPS deployment)
- No automated test suite needed - validation is built into sanitization/CI contracts
- Each user story delivers independent value:
- US2: Clean sanitized modules (buildable)
- US5: Comprehensive documentation (readable)
- US3: Community contribution capability (forkable)
- US4: Ongoing maintenance workflow (sustainable)
- US1: End-to-end deployment validation (usable)
- Success criteria SC-004/SC-005 validated by module/doc checklists in Phase 8
- Security validation (SC-003/SC-009) enforced by gitleaks throughout
- Deployment timing (SC-001) measured during Phase 7