add CLAUDE.md and AGENTS.md; fix README

- Add CLAUDE.md with repo conventions and build strategy docs
- Add AGENTS.md with mandatory workflows for AI agents
- Fix nuclei SBo availability (❎ → ✅)
- Remove stale hydra note (SBo has been updated to 9.6)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

1 files changed, 280 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4623c18
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,280 @@
+# Agent Instructions — Slackware Pentesting Suite
+
+This file governs how AI agents must behave in this repository.
+**Read it in full before taking any action.**
+
+---
+
+## Core Rules
+
+1. **Ask before acting.** If anything about the task is ambiguous — target
+   version, which package, which build strategy — stop and ask. Do not infer
+   intent and proceed.
+2. **Use available skills.** For git operations, commits, PRs, and any task
+   covered by a skill, invoke the relevant skill. Do not improvise a workflow
+   that a skill already defines.
+3. **One package per task.** Never modify multiple packages in a single
+   operation unless explicitly instructed.
+4. **Never skip lint.** Every change must pass `sbolint` before committing.
+   No exceptions.
+5. **Never commit without being asked.** Complete all file edits and
+   verification steps, then wait for explicit instruction to commit.
+
+---
+
+## Repository Layout
+
+Each package lives in its own top-level subfolder:
+
+```
+<package-name>/
+├── <package-name>.SlackBuild   # Main build script
+├── <package-name>.info         # Metadata (version, checksums, download URL)
+├── README                      # Description and usage notes
+├── slack-desc                  # 11-line package description
+├── <package-name>.desktop      # (optional) Desktop entry for GUI apps
+├── doinst.sh                   # (optional) Post-install script
+├── rc.<daemon>                 # (optional) Init script for daemon packages
+├── patches/                    # (optional) Patch directory
+│   ├── series                  # (optional) Ordered patch list
+│   └── *.patch
+└── [...]                       # Other optional files
+```
+
+---
+
+## Package Build Strategies
+
+Before updating or adding a package, identify which build strategy it uses:
+
+| Strategy | Examples | Key indicator |
+|----------|----------|---------------|
+| Go source | ffuf, gobuster, nuclei | `go build`, `REQUIRES="google-go-lang"` |
+| Autotools/cmake source | hydra, cadaver | `./configure` or `cmake` |
+| Binary repack (.deb) | metasploit-framework | `ar p … data.tar.gz \| tar xzv` |
+| Binary repack (.rpm) | nessus | `rpm2cpio … \| cpio -idmv` |
+| Data archive | SecLists, exploitdb, webshells, windows-binaries | no compilation |
+
+The update workflow below applies to all strategies. Differences are called
+out at each step.
+
+---
+
+## Mandatory Workflow: Updating a Package Version
+
+Follow these steps in order. Do not skip or reorder them.
+
+### Step 1 — Identify the build strategy
+
+Read `<package-name>/<package-name>.SlackBuild` to determine which strategy
+the package uses (see table above). This affects how the download URL and
+checksum are handled.
+
+### Step 2 — Update version strings
+
+Edit **both** of the following files, changing the old version to the new one:
+
+- `<package-name>/<package-name>.SlackBuild` — change `VERSION=${VERSION:-<old>}` to the new value
+- `<package-name>/<package-name>.info` — change `VERSION=`, `DOWNLOAD=`
+  (or `DOWNLOAD_x86_64=`), and the corresponding `MD5SUM=` / `MD5SUM_x86_64=`
+
+For the download URL, substitute the new version into the existing URL pattern.
+Set the checksum field to `"placeholder"` — it will be fixed in the next step.
+
+**Binary repack packages:** the download URL typically contains a timestamp or
+build ID embedded by upstream (e.g. Rapid7's `.deb` filenames). Confirm the
+exact URL for the new version before editing.
+
+### Step 3 — Fix the checksum
+
+Run `sbofixinfo` from inside the package directory:
+
+```bash
+cd <package-name> && sbofixinfo
+```
+
+If `sbofixinfo` reports no changes (common when the checksum is a placeholder),
+use the two-pass `sbodl` procedure instead:
+
+```bash
+# Pass 1 — downloads the source; fails because MD5SUM is wrong/placeholder
+cd <package-name> && sbodl
+
+# Compute the real checksum from the downloaded file
+md5sum <downloaded-file>   # adjust filename as needed
+
+# Update the MD5SUM (or MD5SUM_x86_64) in the .info file
+
+# Pass 2 — verifies the checksum; must report "md5sum matches OK"
+cd <package-name> && sbodl
+```
+
+Do not proceed past this step until `sbodl` reports `md5sum matches OK`.
+
+**Binary repack packages:** if `sbodl` cannot download the file automatically
+(e.g. Nessus requires a browser session), download it manually, place it in
+the package directory, compute `md5sum <file>`, update the `.info` file, then
+run `sbodl` for the verification pass.
+
+### Step 4 — Lint
+
+```bash
+cd <package-name> && sbolint
+```
+
+`sbolint` must report no errors. Fix any issues before continuing.
+
+### Step 5 — Report and wait
+
+Present a summary of all changes made and wait for the user to instruct you
+to commit.
+
+---
+
+## Mandatory Workflow: Adding a New Package
+
+Before creating any files, ask the user for:
+
+- The exact `PRGNAM` (package name)
+- The upstream source URL and version
+- The build strategy (source / binary repack / data archive)
+- Any non-SBo runtime dependencies
+
+Then proceed:
+
+1. Create the package directory with all required files:
+   `<prgnam>.SlackBuild`, `<prgnam>.info`, `README`, `slack-desc`
+2. Choose the correct build strategy and follow the scripting rules below.
+3. Run `sbofixinfo`, then `sbodl` (two-pass if needed), then `sbolint`.
+4. Report results and wait for commit instruction.
+
+---
+
+## SlackBuild Scripting Rules
+
+- Base all scripts on the SBo template: https://slackbuilds.org/templates/
+- Use `set -e` (abort on error).
+- Honor `$TMP`, `$BUILD`, `$TAG`, `$OUTPUT`; provide defaults if unset.
+- Detect `$ARCH` and set `SLKCFLAGS` and `LIBDIRSUFFIX` accordingly.
+- Strip ELF binaries and shared objects (skip for pure data packages).
+- Install docs to `/usr/doc/$PRGNAM-$VERSION/`.
+- Always include the `find -L` + `chown`/`chmod` cleanup block before packaging.
+- Build the package with `makepkg -l y -c n`.
+
+### Go source builds
+
+```bash
+export CGO_CPPFLAGS="$SLKCFLAGS"
+export CGO_CFLAGS="$SLKCFLAGS"
+export CGO_CXXFLAGS="$SLKCFLAGS"
+export GOPATH="$(pwd)/.gocache"
+export GOPROXY="https://proxy.golang.org,direct"
+export GOFLAGS="-mod=readonly -buildmode=pie -trimpath -modcacherw"
+LIB_LDFLAGS="-linkmode=external -s -w"
+
+go build -ldflags="$LIB_LDFLAGS" -o "$PKG"/usr/bin/ ./...
+
+# Clean up the Go module cache before packaging
+rm -rf "$GOPATH"
+```
+
+### Binary repack from `.deb`
+
+```bash
+# x86_64 only — exit with error for other arches
+if [ "$ARCH" != "x86_64" ]; then
+  echo "Sorry, $PRGNAM binaries are available for x86_64 only."
+  exit 1
+fi
+
+ar p $CWD/${PRGNAM}_${VERSION}*.deb data.tar.gz | tar xzv
+```
+
+Use `DOWNLOAD="UNSUPPORTED"` and `DOWNLOAD_x86_64="<url>"` in the `.info` file.
+
+### Binary repack from `.rpm`
+
+```bash
+rpm2cpio $CWD/${PRGNAM}-${VERSION}*.rpm | cpio -idmv
+```
+
+Use `DOWNLOAD="UNSUPPORTED"` and `DOWNLOAD_x86_64="<url>"` in the `.info` file.
+
+### Patch support
+
+When patches are needed, store them in `patches/` and apply with:
+
+```bash
+if compgen -G "$CWD/patches/*.patch" > /dev/null; then
+  if [ -f "$CWD/patches/series" ]; then
+    while IFS= read -r PATCH; do
+      [ -z "$PATCH" ] && continue
+      [ "${PATCH#\#}" != "$PATCH" ] && continue
+      patch -p1 -i "$CWD/patches/$PATCH"
+    done < "$CWD/patches/series"
+  else
+    for PATCH in "$CWD"/patches/*.patch; do
+      patch -p1 -i "$PATCH"
+    done
+  fi
+fi
+```
+
+### `.info` file — required fields
+
+```
+PRGNAM="..."
+VERSION="..."
+HOMEPAGE="..."
+DOWNLOAD="..."
+MD5SUM="..."
+DOWNLOAD_x86_64=""
+MD5SUM_x86_64=""
+REQUIRES=""
+MAINTAINER="danix"
+EMAIL="danix@danix.xyz"
+```
+
+- Use `DOWNLOAD="UNSUPPORTED"` when no 32-bit download exists.
+- For packages originally authored by others (e.g. Nessus), preserve the
+  original `MAINTAINER` and `EMAIL` — do not overwrite with danix's details.
+
+### `slack-desc` rules
+
+- Exactly 11 lines, each prefixed with `package-name: `.
+- Line 1: `package-name: package-name (short one-liner description)`
+- Lines 2–11: prose description; blank lines use `package-name:` only.
+- Do not include the ruler line in the committed file.
+
+---
+
+## Git Operations
+
+**Use the commit skill for all commits.** Do not run `git commit` manually.
+
+**Remove symlinks before staging.** `sbodl` creates symlinks in the package
+directory pointing to downloaded source archives. These must never be committed
+to git. Before any `git add`, run from the repo root:
+
+```bash
+find . -type l -delete
+```
+
+Commit conventions:
+- One commit per package add or update.
+- Message format:
+  - Add: `<package-name>: add version X.Y.Z`
+  - Update: `<package-name>: update to X.Y.Z`
+  - Fix: `<package-name>: fix <short description>`
+
+---
+
+## What Requires User Confirmation
+
+Stop and ask before doing any of the following:
+
+- Committing or pushing changes
+- Modifying files in more than one package directory
+- Deleting any file
+- Bypassing the pre-commit hook (`SBOLINT=no`)
+- Any action not covered by the workflows above