docs: mandate Linux CLI tools for file editing over internal tools

Added requirement for AI agents to use standard Linux command-line
tools (sed, awk, grep, patch, cut, etc.) instead of internal text
editing functions.

Rationale:
- Internal editing tools fail frequently with whitespace/encoding issues
- Command-line tools are deterministic and well-tested
- Better error messages and easier verification workflow

Changes:
- AGENTS.md: Added "File Editing Requirements" section with tool usage
- SDLC.md: Added "File Editing Standards" section with patterns

Reference: User feedback that internal editing tools "fail way too much"

💘 Generated with Crush

Assisted-by: GLM-4.7 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
2026-02-20 09:31:23 -05:00
parent aedaabf82c
commit 48d635d8cc
2 changed files with 121 additions and 0 deletions

View File

@@ -434,3 +434,63 @@ Assisted-by: <AI-Model> via Crush <crush@charm.land>
**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`

View File

@@ -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`