From 172bfa78e98302d32846c70ccce96dbafbb3118e Mon Sep 17 00:00:00 2001 From: moilanik Date: Tue, 3 Mar 2026 12:55:24 +0200 Subject: [PATCH] docs: fix outdated references to old implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove QUICK-REFERENCE.md from .ai/ ā€” it contained kube-log project-specific content (hardcoded paths, OpenShift/ArgoCD config) that was leaking into all projects via the symlink. Update docs to match the actual apply.sh implementation: - apply.md: rewrite to reflect curl-only invocation, bootstrap/local phases, factory-reset marker behaviour; remove .ai-instructions.conf and interactive checklist references - architecture.md: remove scripts/ subdirectory and .ai-instructions.conf that were never implemented - apply-usecases.md: remove INSTALL subgraph (rm -rf + cp -r was never done), fix symlink targets to SCRIPT_DIR/.ai - apply-requirements.md: NFR-1 corrected (TTY-gated prompt exists), NFR-4 updated to <150 lines, .ai-instructions.conf removed from out-of-scope list --- .ai/QUICK-REFERENCE.md | 313 ------------------------------------ .ai/ai-root-instructions.md | 2 +- apply.md | 27 ++-- docs/apply-requirements.md | 9 +- docs/apply-usecases.md | 16 +- docs/architecture.md | 27 ++-- 6 files changed, 35 insertions(+), 359 deletions(-) delete mode 100644 .ai/QUICK-REFERENCE.md diff --git a/.ai/QUICK-REFERENCE.md b/.ai/QUICK-REFERENCE.md deleted file mode 100644 index bb75fc1..0000000 --- a/.ai/QUICK-REFERENCE.md +++ /dev/null @@ -1,313 +0,0 @@ -# AI Quick Reference - kube-log Project - -## šŸš« Cluster Access Restrictions - -**AI Assistant does NOT have direct access to Kubernetes clusters:** - -- āŒ **CANNOT run:** `kubectl` commands against live clusters -- āŒ **CANNOT run:** `helm install/upgrade` to live clusters -- āœ… **CAN run:** `helm template` (renders manifests locally) -- āœ… **CAN run:** `helm show values` (inspects charts) -- āœ… **CAN run:** `helm dependency` commands (manages chart dependencies) - -**Why:** -- User manages cluster access and credentials -- Prevents accidental changes to production clusters -- User controls when and how deployments happen - -**What AI can do:** -1. Generate manifests with `helm template` -2. Show what would be deployed -3. Analyze chart configurations -4. Suggest kubectl/helm commands for user to run - -**What user does:** -1. Run kubectl/helm commands themselves -2. Verify changes before applying -3. Control deployment timing -4. Manage cluster credentials - ---- - -## šŸ¢ OpenShift Deployments - -**OpenShift installations are done via ArgoCD from the IaC repository:** - -- **Local dev repo:** `~/koodi/niko-dev/kube-log/` -- **IaC repo:** `~/koodi/niko-dev/IaC/kube-log/` -- **Deployment method:** ArgoCD points to IaC repo - -**Customer-specific file:** -- `values.storage.openshift.dev.yaml` exists in IaC repo (customer side) -- Contains: volume sizes and storageClass settings -- Example: `storageClass: "ocs-storagecluster-cephfs"` -- This file is NOT synced from local dev repo (customer maintains it) - -**When debugging OpenShift issues:** -1. Check ArgoCD sync status -2. Verify customer's `values.storage.openshift.dev.yaml` exists -3. Ensure `values.openshift.yaml` is in IaC repo -4. Remember: OpenShift uses SCC (Security Context Constraints), not PSP - ---- - -## šŸ”„ Syncing to IaC Repository - -**When requested to sync changes to the IaC repository:** - -```bash -# Siirry projektin juureen -cd /Users/moilanik/koodi/niko-dev - -# Kopioi kaikki paitsi .ai kansio, CLAUDE.md ja IaC-spesifiset tiedostot -rsync -av --delete \ - --exclude='.ai/' \ - --exclude='.github/' \ - --exclude='CLAUDE.md' \ - --exclude='.git/' \ - --exclude='tmp/' \ - --exclude='values.storage.openshift.dev.yaml' \ - kube-log/ IaC/kube-log/ - -# Tarkista muutokset -cd IaC/kube-log && git status -``` - -**What this does:** -- Syncs all kube-log changes to separate IaC git repository -- Excludes `.ai/` (AI guidelines - not needed in production repo) -- Excludes `CLAUDE.md` (AI guidelines - kept local only) -- Excludes `.git/` (each repo has its own git history) -- Excludes `tmp/` (temporary files) -- Excludes `values.storage.openshift.dev.yaml` (IaC-only file, customer specific) -- `--delete` removes files from IaC that were deleted from kube-log - -**When to sync:** -- After significant changes to templates, values files, or documentation -- Before committing to IaC repository -- When owner requests: "synkkaa IaC" or similar - -**IMPORTANT:** User will commit and push in IaC repo themselves! - ---- - -## šŸšØ Git Commands - DO NOT RUN - -**These commands are FORBIDDEN without explicit permission:** - -```bash -# āŒ DO NOT RUN THESE: -git add . -git commit -m "..." -git push -git push --force -git reset --hard -``` - -**Instead, SHOW the command and wait:** - -```bash -# āœ… Show this to user: -echo "Run this command:" -echo "git add ." -echo "git commit -m 'your message'" -echo "git push" -``` - ---- - -## šŸŽÆ Common Tasks - -### Check What Changed - -```bash -git status -git diff -git diff values.yaml -``` - -### Restore File from Git - -```bash -# Show command, don't run: -git checkout -- -``` - -### View Git History - -```bash -git log --oneline -20 -git log --oneline --graph --all -``` - -### Test Helm Template - -```bash -# K8s -helm template . --name-template monitoring --namespace kube-log \ - -f values.yaml -f values.storage.dev.yaml - -# OpenShift -helm template . --name-template monitoring --namespace kube-log \ - -f values.yaml -f values.storage.dev.yaml -f values.openshift.yaml -``` - ---- - -## šŸ“‹ Installation Commands - -### Standard Kubernetes (K3s, etc.) - -```bash -# Dev environment -helm upgrade --install kube-log . --namespace kube-log --create-namespace \ - -f values.yaml -f values.storage.dev.yaml - -# Production -helm upgrade --install kube-log . --namespace kube-log --create-namespace \ - -f values.yaml -f values.storage.prod.yaml -``` - -### OpenShift - -**OpenShift deployments are managed via ArgoCD from IaC repo:** -- ArgoCD points to: `~/koodi/niko-dev/IaC/kube-log/` -- Uses: `values.yaml`, `values.storage.openshift.dev.yaml`, `values.openshift.yaml` - -**Manual installation (for testing only):** -```bash -# Dev environment -helm upgrade --install kube-log . --namespace kube-log --create-namespace \ - -f values.yaml -f values.storage.openshift.dev.yaml -f values.openshift.yaml - -# Production -helm upgrade --install kube-log . --namespace kube-log --create-namespace \ - -f values.yaml -f values.storage.openshift.prod.yaml -f values.openshift.yaml -``` - -### Known Issue: First Installation - -First installation may fail with ConfigMap/ServiceAccount error. -Just run the same command **twice**: - -```bash -# First run (may fail) -helm upgrade --install kube-log . --namespace kube-log -f values.yaml -f values.storage.dev.yaml - -# Second run (works) -helm upgrade --install kube-log . --namespace kube-log -f values.yaml -f values.storage.dev.yaml -``` - ---- - -## šŸ” Debugging - -### Check Pod Status - -```bash -kubectl get pods -n kube-log -kubectl get pods -n kube-log -w # Watch mode -``` - -### View Logs - -```bash -kubectl logs -n kube-log deployment/kube-log-minio -kubectl logs -n kube-log deployment/kube-log-minio --tail=50 -kubectl logs -n kube-log kube-log-loki-0 -``` - -### Check PVCs - -```bash -kubectl get pvc -n kube-log -kubectl describe pvc -n kube-log kube-log-minio -``` - -### Port Forwarding - -```bash -# MinIO -kubectl port-forward -n kube-log svc/kube-log-minio 9000:9000 - -# Grafana -kubectl port-forward -n kube-log svc/kube-log-grafana 3000:80 - -# Prometheus -kubectl port-forward -n kube-log svc/kube-log-prometheus-server 9090:80 - -# Loki -kubectl port-forward -n kube-log svc/kube-log-loki 3100:3100 -``` - ---- - -## šŸ—‚ļø File Structure - -``` -kube-log/ -ā”œā”€ā”€ .ai/ # AI guidelines (not in git) -ā”‚ ā”œā”€ā”€ README.md # Main collaboration rules -ā”‚ ā””ā”€ā”€ QUICK-REFERENCE.md # This file -ā”œā”€ā”€ charts/ # Helm dependencies (tgz) -ā”œā”€ā”€ templates/ # Kubernetes manifests -ā”œā”€ā”€ files/ # Config files, dashboards -ā”‚ ā”œā”€ā”€ dashboards/ # Grafana dashboards -ā”‚ ā””ā”€ā”€ grafana-alloy-config.river -ā”œā”€ā”€ values.yaml # K8s baseline config -ā”œā”€ā”€ values.openshift.yaml # OpenShift overrides (if exists) -ā”œā”€ā”€ values.storage.dev.yaml # Dev storage config -ā”œā”€ā”€ values.storage.prod.yaml # Prod storage config -ā””ā”€ā”€ README.md # Main documentation -``` - ---- - -## šŸ’” MinIO Buckets - -Default buckets (created automatically): -- `loki-storage` - Loki chunks and indexes -- `prometheus-metrics` - Prometheus long-term storage (Thanos) -- `tempo-traces` - Tempo distributed tracing - -Credentials (POC): -- Username: `admin` -- Password: `password123` - ---- - -## šŸ” Security Context Patterns - -### Kubernetes (values.yaml) - -```yaml -securityContext: - enabled: true - runAsUser: 1000 - runAsGroup: 1000 - fsGroup: 1000 - runAsNonRoot: true -``` - -### OpenShift (values.openshift.yaml) - -```yaml -securityContext: - enabled: false # Let SCC inject -``` - ---- - -## šŸ“ Remember - -- **NEVER** run git commands without permission -- **ALWAYS** show `git diff` before suggesting commits -- **ASK** if uncertain -- **MINIMAL** changes only -- **TEST** with `helm template` before installing - ---- - -**Last Updated:** 2025-11-05 -**Project Owner:** Controls all git operations -**AI Role:** Analyze, suggest, show commands - never execute git operations \ No newline at end of file diff --git a/.ai/ai-root-instructions.md b/.ai/ai-root-instructions.md index 7db974b..1e39212 100644 --- a/.ai/ai-root-instructions.md +++ b/.ai/ai-root-instructions.md @@ -10,7 +10,7 @@ Your response MUST always begin with: ``` -āœ… ai-root-instructions.md READ \n\n +āœ… ai-root-instructions.md READ\nHave now AI SUPERPOWER\n\n ``` Then continue with your actual response on the next line. diff --git a/apply.md b/apply.md index 046b2fa..affc2aa 100644 --- a/apply.md +++ b/apply.md @@ -4,30 +4,33 @@ How `apply.sh` sets up and maintains AI instructions across all projects. See [R ## Design constraints -`.ai/` is a symlink in every project, pointing back to `ai-superpower/.ai/`. No files are copied. There are no manually maintained project lists. The script discovers projects automatically by scanning for `.git` directories and persists state in `.ai-instructions.conf` so repeat runs are fast and non-interactive. +`.ai/` is a symlink in every project, pointing back to `ai-superpower/.ai/`. No files are copied. There are no manually maintained project lists. The script discovers projects automatically by scanning for `.git` directories. Every run is a full scan ā€” idempotent and stateless. ## How apply.sh works -Run `apply.sh` from anywhere: +`apply.sh` **must be run via `curl | bash`** from the dev root. Direct invocation is blocked: ```bash -./ai-superpower/apply.sh +curl -fsSL https://gitea.nikos-dev.keskikuja.site/niko/ai-superpower/raw/branch/main/apply.sh | bash ``` -The script resolves dev root as its own parent directory. On first run it detects all projects and runs per-project setup. On subsequent runs it reads `.ai-instructions.conf` to skip projects already set up, making repeat runs fast. +**Bootstrap phase** ā€” when piped through bash, `BASH_SOURCE[0]` is empty. The script uses this to detect the bootstrap context, then clones (or pulls) the repo and re-execs the local `apply.sh --bootstrapped DEV_ROOT`. + +**Local phase** ā€” runs with `--bootstrapped` flag. Scans dev root recursively for `.git` directories and runs per-project setup for each one found. ## Project detection -The script recursively scans dev root for directories containing `.git`. `ai-superpower` itself is excluded. All found projects are presented as an interactive checklist ā€” the developer selects which ones to apply to. +The script scans dev root recursively (`-maxdepth 4`) for directories containing `.git`. Any project with a `.ai-superpower` marker file in its root is excluded ā€” this identifies the ai-superpower repo itself regardless of what the directory is named. ## Per-project actions -For each selected project, the script runs the project setup scripts: +For each discovered project: -1. Creates `.ai/` symlink ā†’ `ai-superpower/.ai/` if missing or broken -2. Adds `.ai` to the project's `.gitignore` if not already present -3. Checks for `docs/ai-context.md` ā€” if missing, creates it from a template -4. Checks for `docs/architecture.md` ā€” if missing, warns and offers to create one +1. Creates `project/.ai` ā†’ `ai-superpower/.ai/` symlink if missing or broken +2. Appends `.ai` to `project/.gitignore` if not already present (creates the file if needed) +3. If `docs/` is missing and stdin is a TTY: asks `[y/N]` before creating it +4. Creates `docs/ai-context.md` from template if missing; refreshes if factory-reset marker is still on line 1 +5. Creates `docs/architecture.md` from template if missing; refreshes if factory-reset marker is still on line 1 ## Keeping instructions up to date @@ -40,13 +43,13 @@ git pull Because `.ai/` is a symlink, all projects see the updated instructions immediately ā€” no re-run of `apply.sh` needed. Run `apply.sh` only when adding new projects or repairing broken symlinks. -`apply.sh` is idempotent ā€” safe to run as many times as needed. Existing `docs/` files are never overwritten. +`apply.sh` is idempotent ā€” safe to run as many times as needed. Customised `docs/` files (factory-reset marker absent) are never overwritten. ## Adding a new project The project must be a git repository ā€” `git init` must have been run first. Without a `.git` folder, `apply.sh` will not detect it. -Once initialised, run `apply.sh` ā€” it detects the new project and includes it in the selection. No other configuration needed. +Once initialised, re-run via `curl | bash` from the dev root ā€” it detects the new project automatically. No other configuration needed. ## Project context (ai-context.md) diff --git a/docs/apply-requirements.md b/docs/apply-requirements.md index cbe3629..fbd9492 100644 --- a/docs/apply-requirements.md +++ b/docs/apply-requirements.md @@ -69,11 +69,11 @@ A single bash script that gives any developer AI superpowers across all their pr ## Non-functional requirements -### NFR-1 No interaction (v1) +### NFR-1 Minimal interaction -v1 runs fully automatically. No prompts, no questions, no `read` calls. Compatible with `curl | bash`. +The script is designed to run non-interactively. One exception: when `project/docs/` does not exist and stdin is a TTY, the script asks `[y/N]` before creating the folder. This is gated on TTY detection ā€” in non-interactive environments (piped through curl, CI) it falls back to a printed warning and skip. All other steps run without prompts. -**Future:** the docs/ setup steps (FR-5, FR-6) are the most likely candidates for interactivity in a later version ā€” e.g. asking the developer to describe the project before generating `ai-context.md`, or offering to scaffold `architecture.md`. The code structure must allow this to be added per-project without redesigning the main loop. +**Future:** FR-5.6 and FR-6.5 describe potential interactive scaffolding for `ai-context.md` and `architecture.md`. The code structure must allow this to be added per-project without redesigning the main loop. ### NFR-2 Output @@ -95,7 +95,7 @@ Each project prints a short status line per action taken. Silent for skipped ste ### NFR-4 Size -Target: under 100 lines. Single file, no external scripts. +Target: under 150 lines. Single file, no external scripts. ### NFR-5 Compatibility @@ -110,7 +110,6 @@ Target: under 100 lines. Single file, no external scripts. - Interactive project selection checklist - Interactive docs/ scaffolding (deferred to future version ā€” see FR-5.6, FR-6.5) -- Per-developer configuration file (`.ai-instructions.conf`) - Harnesses (CLAUDE.md, AGENTS.md, .cursor/rules/) - Copy mode ā€” symlinks only - Windows native (WSL required) diff --git a/docs/apply-usecases.md b/docs/apply-usecases.md index a687b1b..195a6b8 100644 --- a/docs/apply-usecases.md +++ b/docs/apply-usecases.md @@ -18,17 +18,9 @@ flowchart TD BS4 --> L1 subgraph LOCAL ["ā”€ā”€ Local mode --bootstrapped flag present ā”€ā”€"] - L1["SCRIPT_DIR = dir of apply.sh\nDEV_ROOT = arg 2\nAI_TARGET = DEV_ROOT/.ai"] + L1["SCRIPT_DIR = dir of apply.sh\nDEV_ROOT = arg 2\nAI_TARGET = SCRIPT_DIR/.ai"] - subgraph INSTALL ["ā”€ā”€ Install .ai/ into dev root ā”€ā”€"] - L1 --> L2["rm -rf DEV_ROOT/.ai"] - L2 --> L3["cp -r ai-superpower/.ai ā†’ DEV_ROOT/.ai"] - L3 --> L4{".ai in DEV_ROOT/.gitignore?"} - L4 -- "No" --> L5["append .ai"] - L4 -- "Yes" --> L6["skip"] - L5 --> SCAN1 - L6 --> SCAN1 - end + L1 --> SCAN1 subgraph SCAN ["ā”€ā”€ Scan DEV_ROOT ā”€ā”€"] SCAN1["find DEV_ROOT\n-mindepth 2 -maxdepth 4\n-name .git -type d"] @@ -41,9 +33,9 @@ flowchart TD subgraph PROJ ["ā”€ā”€ Per-project setup ā”€ā”€"] P1["print ā–ø project-name"] - P1 --> P2{"project/.ai symlink\nā†’ DEV_ROOT/.ai?"} + P1 --> P2{"project/.ai symlink\nā†’ SCRIPT_DIR/.ai?"} P2 -- "Yes" --> P3["skip silently"] - P2 -- "No / wrong / broken" --> P4["ln -sfn DEV_ROOT/.ai project/.ai\nprint āœ“ .ai symlinked"] + P2 -- "No / wrong / broken" --> P4["ln -sfn SCRIPT_DIR/.ai project/.ai\nprint āœ“ .ai symlinked"] P3 --> P5 P4 --> P5 diff --git a/docs/architecture.md b/docs/architecture.md index 463fbc3..c82e6d2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -8,17 +8,14 @@ AI instructions live in one place. Every project symlinks to them ā€” so a `git dev_root/ ā”œā”€ā”€ ai-superpower/ ā† this repo ā”‚ ā”œā”€ā”€ apply.sh ā† single entry point -ā”‚ ā”œā”€ā”€ .ai-instructions.conf ā† managed by apply.sh, gitignored -ā”‚ ā”œā”€ā”€ scripts/ -ā”‚ ā”‚ ā”œā”€ā”€ setup-project.sh ā† creates ai-context.md + architecture.md -ā”‚ ā”‚ ā””ā”€ā”€ symlink-ai.sh ā† creates .ai/ symlink in target project +ā”‚ ā”œā”€ā”€ templates/ ā† ai-context.md and architecture.md templates ā”‚ ā”œā”€ā”€ .ai/ ā† instruction source, symlinked from all projects ā”‚ ā””ā”€ā”€ docs/ ā† this project's own documentation ā”‚ ā”œā”€ā”€ project-a/ ā”‚ ā”œā”€ā”€ .ai/ ā† symlink ā†’ ai-superpower/.ai/ ā”‚ ā””ā”€ā”€ docs/ -ā”‚ ā””ā”€ā”€ ai-context.md ā† project-specific, never synced +ā”‚ ā””ā”€ā”€ ai-context.md ā† project-specific, never overwritten once customised ā”‚ ā””ā”€ā”€ some-folder/ ā””ā”€ā”€ project-b/ ā† nested projects discovered automatically @@ -47,15 +44,15 @@ This modular structure keeps context small and focused. Loading all instruction `apply.sh` is a setup and repair tool, not a distribution tool. Content updates happen via `git pull` ā€” the symlinks ensure all projects see the change immediately. -**Project discovery** ā€” recursively scans dev root for `.git` directories. `ai-superpower` itself is always excluded. All found projects, including nested ones, receive a symlink. +**Project discovery** ā€” recursively scans dev root for `.git` directories up to 4 levels deep. Projects containing a `.ai-superpower` marker file are excluded ā€” this identifies the ai-superpower repo itself regardless of directory name. -**`scripts/symlink-ai.sh`** ā€” creates `project/.ai` ā†’ `ai-superpower/.ai/` as an absolute symlink. If `.ai/` already exists and is a valid symlink, it is left untouched. If it is broken or missing, it is (re)created. +**Symlink creation** ā€” creates `project/.ai` ā†’ `ai-superpower/.ai/` as an absolute symlink. If already correct, skipped silently. If broken or missing, recreated. -**`scripts/setup-project.sh`** ā€” handles per-project context setup: -1. Creates `docs/ai-context.md` from template if missing -2. Checks for `docs/architecture.md` ā€” warns and offers to create if missing - -**`.ai-instructions.conf`** ā€” written and maintained by `apply.sh`. Lives inside this repo, gitignored. Stores which projects have been set up. Treated as a runtime log ā€” the developer does not edit it. +**Per-project docs setup** ā€” handles context file setup directly in `apply.sh`: +1. If `docs/` is missing and stdin is a TTY: asks `[y/N]` before creating it +2. Creates `docs/ai-context.md` and `docs/architecture.md` from templates if missing +3. Refreshes template files if the factory-reset marker is still on line 1 +4. Skips files that have been customised (marker absent) ## Per-project structure @@ -70,8 +67,8 @@ project-x/ ā”‚ ā”œā”€ā”€ skills/ ā”‚ ā””ā”€ā”€ constraints/ ā””ā”€ā”€ docs/ - ā”œā”€ā”€ ai-context.md ā† created by setup-project.sh if missing - ā””ā”€ā”€ architecture.md ā† created if developer confirms + ā”œā”€ā”€ ai-context.md ā† created from template if missing + ā””ā”€ā”€ architecture.md ā† created from template if missing ``` `.ai/` is a symlink ā€” gitignored in target projects, pointing back to the single source in `ai-superpower`. `docs/` is committed and owned by the project team. @@ -84,8 +81,6 @@ project-x/ **One entry point** ā€” `apply.sh` handles setup and repair for all projects. No configuration questions, no mode selection ā€” it always creates symlinks. -**`.ai-instructions.conf` as a runtime artifact** ā€” the script maintains this file like a log. Lives inside this repo but is gitignored ā€” it is personal to the developer and not shared with others who clone this repo. - **Bash over Python or Node** ā€” no runtime to install, works on macOS, Linux, and Windows via WSL. The scripts do file operations and terminal interaction ā€” bash is the right tool. **`docs/ai-context.md` is never synced** ā€” project-specific knowledge is owned by the project team, not this repo. Syncing it would overwrite work the team has done.