infrastructure/mw-pfeddersheim-workstation
2
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align with satware AG best practices

Browse Source 
- 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
This commit is contained in:
ja
2026-03-09 11:02:17 +01:00
parent 5a929898a1
commit 6dbe59e117
17 changed files with 276 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.clinerules/workstation.md
+12
View File
@@ -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
.specify/memory/constitution.md
+34
View File
@@ -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.
AGENTS.md
+32
View File
@@ -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)
CLAUDE.md
-34
View File
@@ -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)
README.md
+46 -21
View File
@@ -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)
---
&copy; 2026 satware AG. All rights reserved.
docs/adr/0001-use-ansible-for-configuration.md
+10
View File
@@ -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
docs/learnings/2026-02-27-initial-setup.md
+12 -1
View File
@@ -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.
- Structure follows PARA for documentation and standard Ansible layout.
docs/learnings/2026-02-27-workstation-organization.md
+9 -3
View File
@@ -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
docs/plans/2026-02-27-initial-setup-plan.md
+42
View File
@@ -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.
NEXT_STEPS.md → docs/plans/2026-02-27-next-steps.md
+12 -1
View File
@@ -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.
docs/product/overview.md → docs/product/project-brief.md
+11 -1
View File
@@ -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).
docs/tech/current-software-audit.md
+12
View File
@@ -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
docs/tech/performance-tuning.md
+12
View File
@@ -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
docs/tech/setup.md
+11 -1
View File
@@ -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 <repo-url> mw-pfeddersheim-workstation
git clone https://git.satware.ai/infrastructure/mw-pfeddersheim-workstation.git
cd mw-pfeddersheim-workstation
```
docs/tech/software-stack.md → docs/tech/stack.md
+11
View File
@@ -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
docs/tech/workstation-health.md
+10 -4
View File
@@ -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.)
implementation_plan.md
-51
View File
@@ -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