From 6dbe59e11791afff485ab77a50c6d367caa19cf7 Mon Sep 17 00:00:00 2001 From: Jane Alesi Date: Mon, 9 Mar 2026 11:02:17 +0100 Subject: [PATCH] docs: align with satware AG best practices - Delete deprecated CLAUDE.md - Create root-level AGENTS.md for AI assistant guidance - Create SDD constitution in .specify/memory/constitution.md - Align documentation with PARA structure (docs/product/project-brief.md, docs/tech/stack.md, docs/plans/) - Add standardized YAML frontmatter to all documentation files - Update README.md with saTway branding and structure --- .clinerules/workstation.md | 12 ++++ .specify/memory/constitution.md | 34 ++++++++++ AGENTS.md | 32 +++++++++ CLAUDE.md | 34 ---------- README.md | 67 +++++++++++++------ .../adr/0001-use-ansible-for-configuration.md | 10 +++ docs/learnings/2026-02-27-initial-setup.md | 13 +++- .../2026-02-27-workstation-organization.md | 12 +++- docs/plans/2026-02-27-initial-setup-plan.md | 42 ++++++++++++ .../plans/2026-02-27-next-steps.md | 13 +++- .../product/{overview.md => project-brief.md} | 12 +++- docs/tech/current-software-audit.md | 12 ++++ docs/tech/performance-tuning.md | 12 ++++ docs/tech/setup.md | 12 +++- docs/tech/{software-stack.md => stack.md} | 11 +++ docs/tech/workstation-health.md | 14 ++-- implementation_plan.md | 51 -------------- 17 files changed, 276 insertions(+), 117 deletions(-) create mode 100644 .specify/memory/constitution.md create mode 100644 AGENTS.md delete mode 100644 CLAUDE.md create mode 100644 docs/plans/2026-02-27-initial-setup-plan.md rename NEXT_STEPS.md => docs/plans/2026-02-27-next-steps.md (78%) rename docs/product/{overview.md => project-brief.md} (79%) rename docs/tech/{software-stack.md => stack.md} (87%) delete mode 100644 implementation_plan.md diff --git a/.clinerules/workstation.md b/.clinerules/workstation.md index 68966db..0e32623 100644 --- a/.clinerules/workstation.md +++ b/.clinerules/workstation.md @@ -1,3 +1,15 @@ +--- +description: >- + Specific rules and standards for managing the mw-pfeddersheim-workstation + infrastructure. +tags: + - workstation + - rules + - infrastructure + - ansible +last_updated: '2026-03-09' +--- + # Workstation Infrastructure Rules ## 1. System Changes diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md new file mode 100644 index 0000000..17f6ad0 --- /dev/null +++ b/.specify/memory/constitution.md @@ -0,0 +1,34 @@ +--- +description: >- + The mw-pfeddersheim-workstation constitution defining the non-negotiable + principles for development and infrastructure management. +tags: + - sdd + - constitution + - principles + - workstation +last_updated: '2026-03-09' +--- + +# mw-pfeddersheim-workstation Constitution + +## Article I: Intent is Truth +The source of truth for all system changes is the intent documented in the `specs/` and `docs/` directories. No configuration change should exist without a documented rationale. + +## Article II: Baby Steps™ Imperative +All modifications MUST follow the Baby Steps™ methodology: +1. Atomic changes only. +2. Focus on process over outcome. +3. One task at a time. +4. Complete and verify before moving to the next. +5. Mandatory incremental verification. +6. Document progress in `docs/learnings/`. + +## Article III: Configuration-as-Code +All system configurations that can be automated MUST be managed via Ansible roles. Manual changes are allowed only when automation is impossible or prohibitively complex, and they MUST be documented in `docs/tech/manual-overrides.md`. + +## Article IV: Zero-Trust Security +No raw secrets, tokens, or private keys shall ever be committed to the repository. Use `ansible-vault` or system-level environment variables. + +## Article V: Performance & Reliability +All infrastructure changes should prioritize system stability and performance. Maintenance scripts MUST be robust and follow the satware AG bash script standards. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7b1fc8f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,32 @@ +# AGENTS.md (mw-pfeddersheim-workstation) + +## Project Overview +This repository manages the infrastructure, configuration, and maintenance for Michael Wegener's primary workstation at satware AG (Pfeddersheim location). It uses Ansible for system configuration and shell scripts for maintenance. + +## Key Directories +- `ansible/`: Configuration-as-Code via Ansible roles and playbooks. +- `docs/`: PARA-structured documentation (Product, ADR, Learnings, Tech). +- `scripts/`: Automation and maintenance scripts. +- `config/`: Templates for system configuration files. + +## Essential Commands +| Task | Command | +|------|---------| +| Apply Configuration | `ansible-playbook ansible/workstation.yml` | +| System Maintenance | `bash scripts/maintenance.sh` | +| Verify Ansible | `ansible-playbook ansible/workstation.yml --check` | + +## Standards +- **Baby Steps™**: Small, verifiable changes (<200 LOC per commit). +- **PARA Documentation**: Keep documentation updated in the `docs/` folder. +- **Zero-Trust**: Secrets must be handled via Ansible Vault or environment variables. + +## Guardrails +- **NEVER** commit raw secrets to the repository. +- **ALWAYS** run Ansible with `--check` before applying changes. +- **NEVER** modify system configuration directly if it can be managed via Ansible. + +## Rules Hierarchy +- Global rules: `Rules/` +- Project rules: `.clinerules/` +- Agent instructions: `AGENTS.md` (this file) diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 37008be..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,34 +0,0 @@ -# CLAUDE.md - mw-pfeddersheim-workstation Infrastructure - -## Project Overview -This repository manages the DevOps configuration, software stack, and maintenance scripts for the **mw-pfeddersheim-workstation**. It follows the **saTway** methodology for workstations. - -## Key Directories -- `docs/`: Documentation (Product, Tech, ADR, Learnings) -- `scripts/`: Maintenance and automation scripts -- `config/`: System and application configurations -- `ansible/`: Provisioning and configuration management -- `.clinerules/`: Project-specific AI behavior rules - -## Essential Commands -| Command | Purpose | -|---------|---------| -| `bash scripts/maintenance.sh` | Run standard system maintenance | -| `bash scripts/backup.sh` | Trigger local backup routines | -| `ansible-playbook ansible/workstation.yml` | Apply workstation configuration | - -## Standards -- **Methodology**: Baby Steps™, TDD for scripts -- **Security**: Zero-Trust, Gitleaks for secrets -- **Documentation**: All changes documented in `docs/` -- **Scripting**: Bash scripts must use `set -euo pipefail` - -## Guardrails -- **NEVER** commit secrets or private keys -- **ALWAYS** test scripts in a safe manner before full execution -- **PREFER** Ansible for system-wide configuration changes - -## Rules Hierarchy -1. `Rules/` (Global satware AG policies) -2. `.clinerules/` (Project-specific workstation rules) -3. `CLAUDE.md` (This file) diff --git a/README.md b/README.md index a242ab6..75cd297 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,65 @@ -# saTway DevOps - mw-pfeddersheim-workstation +--- +description: >- + Infrastructure-as-Code and maintenance repository for Michael Wegener's + primary workstation at satware AG (Pfeddersheim location). +tags: + - workstation + - ansible + - infrastructure-as-code + - linux + - automation +last_updated: '2026-03-09' +--- -This repository contains the infrastructure-as-code, configuration, and maintenance scripts for the **mw-pfeddersheim-workstation**. +# saTway® Infrastructure - mw-pfeddersheim-workstation + +This repository manages the configuration, software stack, and maintenance scripts for Michael Wegener's primary workstation. It ensures a reproducible, secure, and optimized environment following **satware AG** best practices. ## 🚀 Quick Start -To apply the current configuration to the workstation: +To apply the current configuration or run maintenance: ```bash -# Apply Ansible configuration +# 1. Verify configuration with a dry run +ansible-playbook ansible/workstation.yml --check + +# 2. Apply configuration locally ansible-playbook ansible/workstation.yml -# Run maintenance +# 3. Run automated maintenance bash scripts/maintenance.sh ``` -## 📂 Structure +## 📂 Project Structure -- `ansible/`: Ansible playbooks and roles for system configuration. -- `config/`: Configuration files for various system components. -- `docs/`: Comprehensive documentation following the satware AG PARA structure. -- `scripts/`: System maintenance and automation scripts. +| Directory | Purpose | +|-----------|---------| +| `ansible/` | Configuration-as-Code (Roles: `common`, `dev-tools`, `maintenance`) | +| `config/` | System configuration templates (`.j2`) | +| `docs/` | PARA-structured documentation (`product`, `adr`, `learnings`, `tech`) | +| `scripts/` | Maintenance and automation scripts | ## 🛠 Software Stack -The workstation is equipped with the following core tools: -- **Languages**: Node.js 22+, Python 3.12+, PHP 8.4 -- **DevOps**: Docker, Ansible, Terraform (planned) -- **Editors**: IntelliJ IDEA, VS Code -- **Shell**: Bash, Git +- **Languages**: Node.js 22 LTS, Python 3.12+, PHP 8.4 +- **Automation**: Ansible, Docker +- **Environment**: Manjaro/Arch Linux, Bash -## 📜 Principles +## 📜 Core Principles -- **Baby Steps™**: Small, verifiable changes. -- **Zero-Trust**: No secrets in the repository, use Ansible Vault or secret managers. -- **TDD**: Write tests for scripts using `bats` (planned). +- **Baby Steps™**: All changes are small, atomic, and verifiable. +- **Spec-Driven Development**: Intent-first development with explicit documentation. +- **Zero-Trust**: Secrets are managed via `ansible-vault` or environment variables; never committed raw. -## 📄 License +## 📄 Documentation -Proprietary - satware AG. All rights reserved. +Comprehensive documentation is available in the `docs/` directory: +- [Project Brief](docs/product/project-brief.md) +- [Setup Guide](docs/tech/setup.md) +- [Software Stack](docs/tech/stack.md) +- [Software Audit](docs/tech/current-software-audit.md) +- [Decision Records](docs/adr/0001-use-ansible-for-configuration.md) + +--- + +© 2026 satware AG. All rights reserved. diff --git a/docs/adr/0001-use-ansible-for-configuration.md b/docs/adr/0001-use-ansible-for-configuration.md index 4ef157e..1394e8a 100644 --- a/docs/adr/0001-use-ansible-for-configuration.md +++ b/docs/adr/0001-use-ansible-for-configuration.md @@ -1,3 +1,13 @@ +--- +description: >- + Decision to use Ansible for managing workstation configuration and lifecycle. +tags: + - adr + - ansible + - configuration-management +last_updated: '2026-03-09' +--- + # ADR 1: Use Ansible for Workstation Configuration Management ## Status diff --git a/docs/learnings/2026-02-27-initial-setup.md b/docs/learnings/2026-02-27-initial-setup.md index 8ca559f..712ed9d 100644 --- a/docs/learnings/2026-02-27-initial-setup.md +++ b/docs/learnings/2026-02-27-initial-setup.md @@ -1,3 +1,14 @@ +--- +description: >- + Initial setup and baseline verification for the mw-pfeddersheim-workstation + infrastructure project. +tags: + - learning + - setup + - baseline +last_updated: '2026-03-09' +--- + # Initial Setup and Baseline - 2026-02-27 ## Context @@ -15,4 +26,4 @@ Starting the formal infrastructure management for the `mw-pfeddersheim-workstati ## Lessons Learned - Git status confirms all initial files are untracked. -- Structure follows PARA for documentation and standard Ansible layout. \ No newline at end of file +- Structure follows PARA for documentation and standard Ansible layout. diff --git a/docs/learnings/2026-02-27-workstation-organization.md b/docs/learnings/2026-02-27-workstation-organization.md index e52967d..dea9920 100644 --- a/docs/learnings/2026-02-27-workstation-organization.md +++ b/docs/learnings/2026-02-27-workstation-organization.md @@ -1,7 +1,13 @@ --- -description: Learnings from workstation cleanup and project organization -tags: [workstation, cleanup, git, disk-usage] -last_updated: 2026-02-27 +description: >- + Learnings from workstation cleanup, disk space optimization, and Git + repository organization. +tags: + - workstation + - cleanup + - git + - disk-usage +last_updated: '2026-02-27' --- # Workstation Organization diff --git a/docs/plans/2026-02-27-initial-setup-plan.md b/docs/plans/2026-02-27-initial-setup-plan.md new file mode 100644 index 0000000..7731fd9 --- /dev/null +++ b/docs/plans/2026-02-27-initial-setup-plan.md @@ -0,0 +1,42 @@ +--- +description: >- + Historical implementation plan for the initial baseline of the + mw-pfeddersheim-workstation infrastructure. +tags: + - plan + - history + - baseline +last_updated: '2026-02-27' +--- + +# Initial Implementation Plan - 2026-02-27 + +Establish a stable infrastructure baseline for the mw-pfeddersheim-workstation by committing existing files, implementing missing Ansible tasks, and cleaning up legacy tool remnants. + +This plan focuses on transition the repository from an uncommitted state to a managed baseline. It addresses the user's specific request to remove VS Code remnants and local AI tools while setting up a robust maintenance routine through Ansible and shell scripts. The goal is to ensure Michael Wegener's workstation is reproducible and follows the defined saTway standards. + +## Files & Components + +Updates existing Ansible roles and creates a new learning log for context restoration. + +### New files: +- `docs/learnings/2026-02-27-initial-setup.md`: Documentation of the initial repository state and first baseline. +- `ansible/roles/maintenance/tasks/main.yml`: Implementation of system cleanup and maintenance tasks. +- `ansible/roles/dev-tools/tasks/main.yml`: Implementation of development tool management (installation of core tools, removal of legacy ones). + +### Existing files to be modified: +- `scripts/maintenance.sh`: Enhanced to handle the `--check` flag and integrate better with Ansible-driven cleanup. + +### Configuration updates: +- `.gitignore`: Ensure all relevant system and Ansible files are correctly tracked or ignored. + +## Implementation Order +The sequence is designed to establish a git baseline before making system-level changes. + +1. Create initial learning log for documentation. +2. Perform initial git commit of all untracked infrastructure files. +3. Create `feat/initial-baseline` branch for subsequent changes. +4. Implement `ansible/roles/maintenance/tasks/main.yml` including VS Code and AI tool cleanup. +5. Implement `ansible/roles/dev-tools/tasks/main.yml` for core tool validation. +6. Update `scripts/maintenance.sh` to support `--check` mode. +7. Execute Ansible playbook in check mode, then apply. diff --git a/NEXT_STEPS.md b/docs/plans/2026-02-27-next-steps.md similarity index 78% rename from NEXT_STEPS.md rename to docs/plans/2026-02-27-next-steps.md index 192c295..d7d51a2 100644 --- a/NEXT_STEPS.md +++ b/docs/plans/2026-02-27-next-steps.md @@ -1,4 +1,15 @@ -# Next Session Tasks +--- +description: >- + Immediate next steps and priority tasks for workstation cleanup and repository + management. +tags: + - plan + - history + - next-steps +last_updated: '2026-02-27' +--- + +# Next Session Tasks - 2026-02-27 ## Priority 1 (Clean Up) - [ ] Address permission issues in `PhpstormProjects/satag-amicron-entity-bundle` and `SatagAmicronSix` to finish removal. diff --git a/docs/product/overview.md b/docs/product/project-brief.md similarity index 79% rename from docs/product/overview.md rename to docs/product/project-brief.md index b4acf6c..78e7b10 100644 --- a/docs/product/overview.md +++ b/docs/product/project-brief.md @@ -1,4 +1,14 @@ -# mw-pfeddersheim-workstation Infrastructure Overview +--- +description: >- + High-level overview and purpose of the mw-pfeddersheim-workstation project. +tags: + - project-brief + - infrastructure + - overview +last_updated: '2026-03-09' +--- + +# mw-pfeddersheim-workstation Project Brief ## Purpose This repository serves as the single source of truth for the configuration and lifecycle management of Michael Wegener's primary workstation at satware AG (Pfeddersheim location). diff --git a/docs/tech/current-software-audit.md b/docs/tech/current-software-audit.md index ce89674..af98922 100644 --- a/docs/tech/current-software-audit.md +++ b/docs/tech/current-software-audit.md @@ -1,3 +1,15 @@ +--- +description: >- + Detailed inventory and audit of workstation software, identifying core tools, + categorized packages, and candidates for removal. +tags: + - software-audit + - inventory + - maintenance + - cleanup +last_updated: '2026-03-09' +--- + # Software Audit - mw-pfeddersheim-workstation (2026-02-27) ## 1. Core Development Tools diff --git a/docs/tech/performance-tuning.md b/docs/tech/performance-tuning.md index 0c848dc..e3392c8 100644 --- a/docs/tech/performance-tuning.md +++ b/docs/tech/performance-tuning.md @@ -1,3 +1,15 @@ +--- +description: >- + Detailed performance optimization strategies, kernel parameter tuning, and + system maintenance routines for the mw-pfeddersheim-workstation. +tags: + - performance + - optimization + - kernel-tuning + - maintenance +last_updated: '2026-03-09' +--- + # mw-pfeddersheim-workstation Performance Tuning ## Overview diff --git a/docs/tech/setup.md b/docs/tech/setup.md index fbba812..c4660e9 100644 --- a/docs/tech/setup.md +++ b/docs/tech/setup.md @@ -1,3 +1,13 @@ +--- +description: >- + Workstation bootstrapping and setup instructions using Ansible. +tags: + - setup + - bootstrap + - ansible +last_updated: '2026-03-09' +--- + # Workstation Setup Guide This guide describes how to bootstrap the **mw-pfeddersheim-workstation** infrastructure on a fresh installation. @@ -13,7 +23,7 @@ This guide describes how to bootstrap the **mw-pfeddersheim-workstation** infras ```bash mkdir -p ~/infrastructure cd ~/infrastructure - git clone mw-pfeddersheim-workstation + git clone https://git.satware.ai/infrastructure/mw-pfeddersheim-workstation.git cd mw-pfeddersheim-workstation ``` diff --git a/docs/tech/software-stack.md b/docs/tech/stack.md similarity index 87% rename from docs/tech/software-stack.md rename to docs/tech/stack.md index 64ef167..b68b13c 100644 --- a/docs/tech/software-stack.md +++ b/docs/tech/stack.md @@ -1,3 +1,14 @@ +--- +description: >- + Detailed inventory of the core software stack, OS context, and maintenance + policies for the mw-pfeddersheim-workstation. +tags: + - software-stack + - inventory + - tech-stack +last_updated: '2026-03-09' +--- + # Software Stack - mw-pfeddersheim-workstation ## Core Development Environment diff --git a/docs/tech/workstation-health.md b/docs/tech/workstation-health.md index df4c049..d408484 100644 --- a/docs/tech/workstation-health.md +++ b/docs/tech/workstation-health.md @@ -1,7 +1,13 @@ --- -description: Workstation health and specification baseline -tags: [infrastructure, health-check, workstation] -last_updated: 2026-03-06 +description: >- + Comprehensive health report for the mw-pfeddersheim-workstation, including + system specifications, current status, and runtime environment details. +tags: + - infrastructure + - health-check + - workstation + - monitoring +last_updated: '2026-03-09' --- # Workstation Health Report: mw-manjaro-pf @@ -13,7 +19,7 @@ last_updated: 2026-03-06 - **Secondary Disk**: 500 GB SATA SSD (Samsung 840 EVO) -> `/home/mw/models` - **OS**: Manjaro Linux (Kernel 6.12) -## Current Health Status (2026-03-06) +## Current Health Status (2026-03-09) - **Disk Usage (/)**: 75% (333G used, 113G free) - **Maintenance**: - Orphaned packages cleaned (ninja, texlive components, etc.) diff --git a/implementation_plan.md b/implementation_plan.md deleted file mode 100644 index cbc3a67..0000000 --- a/implementation_plan.md +++ /dev/null @@ -1,51 +0,0 @@ -# Implementation Plan - -Establish a stable infrastructure baseline for the mw-pfeddersheim-workstation by committing existing files, implementing missing Ansible tasks, and cleaning up legacy tool remnants. - -This plan focuses on transition the repository from an uncommitted state to a managed baseline. It addresses the user's specific request to remove VS Code remnants and local AI tools while setting up a robust maintenance routine through Ansible and shell scripts. The goal is to ensure Michael Wegener's workstation is reproducible and follows the defined saTway standards. - -[Types] -No custom type system changes are required for this infrastructure-heavy task. - -[Files] -Updates existing Ansible roles and creates a new learning log for context restoration. - -Detailed breakdown: -- New files: - - `docs/learnings/2026-02-27-initial-setup.md`: Documentation of the initial repository state and first baseline. - - `ansible/roles/maintenance/tasks/main.yml`: Implementation of system cleanup and maintenance tasks. - - `ansible/roles/dev-tools/tasks/main.yml`: Implementation of development tool management (installation of core tools, removal of legacy ones). -- Existing files to be modified: - - `scripts/maintenance.sh`: Enhanced to handle the `--check` flag and integrate better with Ansible-driven cleanup. -- Configuration updates: - - `.gitignore`: Ensure all relevant system and Ansible files are correctly tracked or ignored. - -[Functions] -No software functions are being implemented; focus is on shell script logic and Ansible tasks. - -Detailed breakdown: -- Modified scripts: - - `scripts/maintenance.sh`: Add parameter parsing for `--check` and implement non-destructive validation mode. - -[Classes] -No classes are used in this project. - -[Dependencies] -Ansible 10.x and standard Arch Linux packages (paccache, checkupdates, journalctl). - -[Implementation Order] -The sequence is designed to establish a git baseline before making system-level changes. - -1. Create initial learning log for documentation. -2. Perform initial git commit of all untracked infrastructure files. -3. Create `feat/initial-baseline` branch for subsequent changes. -4. Implement `ansible/roles/maintenance/tasks/main.yml` including VS Code and AI tool cleanup. -5. Implement `ansible/roles/dev-tools/tasks/main.yml` for core tool validation. -6. Update `scripts/maintenance.sh` to support `--check` mode. -7. Execute Ansible playbook in check mode, then apply. - -task_progress Items: -- [ ] Step 1: Document initial state and create baseline commit -- [ ] Step 2: Implement maintenance role with cleanup tasks (VS Code, AI tools) -- [ ] Step 3: Implement dev-tools role for core workstation software -- [ ] Step 4: Enhance maintenance script and verify via Ansible check mode \ No newline at end of file