niko/ai-superpower
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: fix outdated references to old implementation

Browse Source 
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
This commit is contained in:
moilanik 2026-03-03 12:55:24 +02:00
parent cd6f8b5c81
commit 172bfa78e9
6 changed files with 35 additions and 359 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

313
.ai/QUICK-REFERENCE.md
View File

@ -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 <commit-hash> -- <file-path>
```
### 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

2
.ai/ai-root-instructions.md
View File

@ -10,7 +10,7 @@
Your response MUST always begin with: 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. Then continue with your actual response on the next line.

27
apply.md
View File

@ -4,30 +4,33 @@ How `apply.sh` sets up and maintains AI instructions across all projects. See [R
## Design constraints ## 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 ## 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 ```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 ## 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 ## 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 1. Creates `project/.ai` → `ai-superpower/.ai/` symlink if missing or broken
2. Adds `.ai` to the project's `.gitignore` if not already present 2. Appends `.ai` to `project/.gitignore` if not already present (creates the file if needed)
3. Checks for `docs/ai-context.md` — if missing, creates it from a template 3. If `docs/` is missing and stdin is a TTY: asks `[y/N]` before creating it
4. Checks for `docs/architecture.md` — if missing, warns and offers to create one 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 ## 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. 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 ## 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. 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) ## Project context (ai-context.md)

9
docs/apply-requirements.md
View File

@ -69,11 +69,11 @@ A single bash script that gives any developer AI superpowers across all their pr
## Non-functional requirements ## 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 ### NFR-2 Output
@ -95,7 +95,7 @@ Each project prints a short status line per action taken. Silent for skipped ste
### NFR-4 Size ### NFR-4 Size
Target: under 100 lines. Single file, no external scripts. Target: under 150 lines. Single file, no external scripts.
### NFR-5 Compatibility ### NFR-5 Compatibility
@ -110,7 +110,6 @@ Target: under 100 lines. Single file, no external scripts.
- Interactive project selection checklist - Interactive project selection checklist
- Interactive docs/ scaffolding (deferred to future version — see FR-5.6, FR-6.5) - 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/) - Harnesses (CLAUDE.md, AGENTS.md, .cursor/rules/)
- Copy mode — symlinks only - Copy mode — symlinks only
- Windows native (WSL required) - Windows native (WSL required)

16
docs/apply-usecases.md
View File

@ -18,17 +18,9 @@ flowchart TD
BS4 --> L1 BS4 --> L1
subgraph LOCAL ["── Local mode --bootstrapped flag present ──"] 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 --> SCAN1
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
subgraph SCAN ["── Scan DEV_ROOT ──"] subgraph SCAN ["── Scan DEV_ROOT ──"]
SCAN1["find DEV_ROOT\n-mindepth 2 -maxdepth 4\n-name .git -type d"] 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 ──"] subgraph PROJ ["── Per-project setup ──"]
P1["print ▸ project-name"] 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 -- "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 P3 --> P5
P4 --> P5 P4 --> P5

27
docs/architecture.md
View File

@ -8,17 +8,14 @@ AI instructions live in one place. Every project symlinks to them — so a `git
dev_root/ dev_root/
├── ai-superpower/ ← this repo ├── ai-superpower/ ← this repo
│ ├── apply.sh ← single entry point │ ├── apply.sh ← single entry point
│ ├── .ai-instructions.conf ← managed by apply.sh, gitignored │ ├── templates/ ← ai-context.md and architecture.md templates
│ ├── scripts/
│ │ ├── setup-project.sh ← creates ai-context.md + architecture.md
│ │ └── symlink-ai.sh ← creates .ai/ symlink in target project
│ ├── .ai/ ← instruction source, symlinked from all projects │ ├── .ai/ ← instruction source, symlinked from all projects
│ └── docs/ ← this project's own documentation │ └── docs/ ← this project's own documentation
│ │
├── project-a/ ├── project-a/
│ ├── .ai/ ← symlink → ai-superpower/.ai/ │ ├── .ai/ ← symlink → ai-superpower/.ai/
│ └── docs/ │ └── docs/
│ └── ai-context.md ← project-specific, never synced │ └── ai-context.md ← project-specific, never overwritten once customised
│ │
└── some-folder/ └── some-folder/
└── project-b/ ← nested projects discovered automatically └── 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. `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: **Per-project docs setup** — handles context file setup directly in `apply.sh`:
1. Creates `docs/ai-context.md` from template if missing 1. If `docs/` is missing and stdin is a TTY: asks `[y/N]` before creating it
2. Checks for `docs/architecture.md` — warns and offers to create if missing 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
**`.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. 4. Skips files that have been customised (marker absent)
## Per-project structure ## Per-project structure
@ -70,8 +67,8 @@ project-x/
│ ├── skills/ │ ├── skills/
│ └── constraints/ │ └── constraints/
└── docs/ └── docs/
├── ai-context.md ← created by setup-project.sh if missing ├── ai-context.md ← created from template if missing
└── architecture.md ← created if developer confirms └── 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. `.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. **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. **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. **`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.