diff --git a/AGENTS.md b/AGENTS.md index 2cbbad8..814f7e1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -434,3 +434,63 @@ Assisted-by: via Crush **Last Updated**: 2026-02-19 **SDLC Enforcement**: Pre-commit hook + mandatory workflow documentation + +--- + +## File Editing Requirements + +### Use Linux Command-Line Tools (MANDATORY) + +**When editing files, prefer Linux command-line tools over internal editing functions.** + +**Preferred Tools:** +- `sed` - Stream editor for text transformations +- `awk` - Pattern scanning and processing +- `grep` - Search and filter text +- `patch` - Apply diff files +- `cut` - Remove sections from lines +- `tr` - Translate/delete characters +- `head`/`tail` - Output first/last lines +- `sort`/`uniq` - Sort and deduplicate +- `xargs` - Build command lines from input + +**When to Use Each:** +```bash +# Replace text in file +sed -i 's/old/new/g' file.txt + +# Replace on specific line +sed -i '42s/old/new/' file.txt + +# Append after line matching pattern +sed -i '/pattern/a\new line' file.txt + +# Delete lines matching pattern +sed -i '/pattern/d' file.txt + +# Extract specific column +awk '{print $2}' file.txt + +# Process based on condition +awk '/pattern/ {print $1, $3}' file.txt + +# Search and replace with regex +sed -i -E 's/pattern/replacement/g' file.txt + +# Apply a patch +patch -p1 < changes.diff +``` + +**Why This Matters:** +- Internal editing tools fail frequently with whitespace/encoding issues +- Command-line tools are deterministic and well-tested +- Easier to verify changes before applying +- Better error messages when something goes wrong +- Can preview changes with `sed 's/old/new/g' file` (no -i) first + +**Workflow:** +1. Read file first: `cat file.txt` or `head -n 50 file.txt` +2. Preview change: `sed 's/old/new/g' file.txt` (no -i) +3. Apply change: `sed -i 's/old/new/g' file.txt` +4. Verify: `git diff file.txt` + diff --git a/docs/SDLC.md b/docs/SDLC.md index 0d40b41..994e2de 100644 --- a/docs/SDLC.md +++ b/docs/SDLC.md @@ -390,3 +390,64 @@ md5sum -c knel-football-secure.iso.md5 **Copyright © 2026 Known Element Enterprises LLC** **License: GNU Affero General Public License v3.0 only** + +--- + +## File Editing Standards + +### Linux Command-Line Tools (MANDATORY for AI Agents) + +**AI agents MUST use standard Linux command-line tools for file editing, not internal text editing functions.** + +**Rationale:** Internal editing tools frequently fail due to: +- Whitespace encoding mismatches (tabs vs spaces) +- Line ending differences (CRLF vs LF) +- Unicode/encoding issues +- Exact text matching requirements that are brittle + +**Approved Tools:** +| Tool | Use Case | +|------|----------| +| `sed` | Search/replace, line insertions/deletions | +| `awk` | Field extraction, conditional processing | +| `grep` | Pattern matching, filtering | +| `patch` | Apply diff/patch files | +| `cut` | Column extraction | +| `tr` | Character translation | +| `head`/`tail` | Preview file sections | +| `sort`/`uniq` | Sort and deduplicate | + +**Standard Patterns:** + +```bash +# In-place text replacement +sed -i 's/old_text/new_text/g' file.txt + +# Replace on specific line number +sed -i '42s/old/new/' file.txt + +# Insert line after match +sed -i '/pattern/a\new_line' file.txt + +# Delete matching lines +sed -i '/pattern/d' file.txt + +# Multi-line replacement with extended regex +sed -i -E 's/pattern/replacement/g' file.txt + +# Extract specific field (whitespace-delimited) +awk '{print $2}' file.txt + +# Conditional processing +awk '/pattern/ {print $1}' file.txt + +# Preview changes BEFORE applying (no -i flag) +sed 's/old/new/g' file.txt | head -20 +``` + +**Verification Workflow:** +1. Read file: `cat file.txt` or `head -n 50 file.txt` +2. Preview change: `sed 's/old/new/g' file.txt` (no `-i`) +3. Apply change: `sed -i 's/old/new/g' file.txt` +4. Verify result: `git diff file.txt` +