generate-project-rules.sh

#!/usr/bin/env bash
# generate-project-rules.sh — Generate universal agent rules for any project
#
# Run from any project directory:
#   /path/to/agent-toolkit/generate-project-rules.sh
#
# Creates AGENTS.md (read by Codex, Claude Code, Gemini CLI) and
# optionally .cursorrules (read by Cursor). Same content, different filenames.

set -e

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SHARED="$SCRIPT_DIR/shared"

echo "Generating project agent rules..."

# Check we're in a project (has git or package files)
if [ ! -d .git ] && [ ! -f package.json ] && [ ! -f pyproject.toml ] && [ ! -f go.mod ] && [ ! -f Cargo.toml ]; then
    echo "Warning: this doesn't look like a project root. Continue? (y/n)"
    read -r answer
    [ "$answer" != "y" ] && exit 0
fi

# Build the universal rules file from toolkit content
cat > AGENTS.md << 'HEADER'
# Project Agent Rules
<!-- Auto-generated by agent-toolkit. Edit the toolkit, not this file. -->
<!-- Regenerate with: /path/to/agent-toolkit/generate-project-rules.sh -->

HEADER

# Guardrails (quick reference)
if [ -f "$SHARED/guardrails-quick.md" ]; then
    echo "## Safety Rules" >> AGENTS.md
    echo "" >> AGENTS.md
    # Strip the header, keep the content
    tail -n +3 "$SHARED/guardrails-quick.md" >> AGENTS.md
    echo "" >> AGENTS.md
fi

# Append key workflow rules from skills (extracted, not full skills)
cat >> AGENTS.md << 'WORKFLOW'
## Workflow Rules

### Build: One Feature at a Time
- Skeleton first (greenfield), then one feature slab at a time
- Each slab: setup → security → TDD → integrate → precommit → commit
- Stop between slabs. Present result, wait for confirmation before next.
- Frontend slabs wait until backend flow is validated

### TDD: Meaningful Tests Only
- Every test has specific value assertions (assertEqual, toBe, toEqual)
- Realistic test data ("Maria Garcia", not "foo"). Real formats, not placeholders.
- Tests MUST fail if the feature code is deleted
- No assertTrue(True), no toBeTruthy(), no assertion-free tests
- No mocking the thing being tested

### Before Every Commit
- All user instructions addressed? (re-read every message)
- Tests meaningful? (no sloppy assertions)
- SOLID/DRY/KISS/YAGNI principles checked?
- Verified in running app? (tests passing is not enough)
- Never say "fixed" or "done" — say "change ready, please verify: [action]"

### Frontend Rules (from real bugs)
- No Promise.all for independent page data — load each source separately
- Every setLoading(true) has finally { setLoading(false) }
- Every API response array guarded with Array.isArray()
- No raw fetch() in components — use typed API client
- No silent catches — show toast.error or user-visible message
- Core features never conditionally hidden — always show with empty state
- Dynamic text: truncate + overflow-hidden + max-w
- No false success messages — check response.ok before showing "Saved!"
- File input: validate on BOTH click AND drag-drop paths
- User URLs: validate scheme (prevent javascript: XSS)
- ErrorBoundary wraps all routes (day 1, not polish)

### Backend Rules (from real bugs)
- Never mix async HTTP in sync endpoints (silent failures)
- Never combine ThreadPoolExecutor + asyncio.run
- Auto-create .env.example when code reads env vars
- Config changes must not require restart — lazy-load from DB
- Every external API needs at least 1 live test with separate marker
- N+1 queries: fix at any scale (correctness issue)

### Naming
- Full descriptive variable names. No single-letter (except i/j/k/e). No abbreviations.
- Name user-facing features before building — naming shapes perception.

### Security
- No hardcoded secrets — use environment variables
- Parameterized queries — no string concatenation for SQL
- Input validation on every user-facing endpoint
- No secrets in logs
- Personal data and user preferences: always encrypt at rest (bcrypt for passwords, AES-256 for data)
- Project rules override these defaults. If this project has its own conventions (in CLAUDE.md, DECISIONS.md, etc.), follow the project — not this file.

### Git
- Branch names: `feature/<name>`, `fix/<name>`, `refactor/<name>`, `chore/<name>`
- PR titles: concise and descriptive — not "Update code" or "Fix stuff"
- One slab = one commit. Commit message explains what and why.
WORKFLOW

# If project-state template exists, mention it
if [ -f "$SHARED/project-state-template.md" ]; then
    cat >> AGENTS.md << 'STATE'

## Project State
Create `project-state.md` at project root to track: core intent, key decisions, feature status (works/placeholder/broken), active warnings. All agents read this at start, write at end.
STATE
fi

# Append agent instructions (flattened — no sub-agent spawning needed)
AGENTS_DIR="$SCRIPT_DIR/agents"

if [ -d "$AGENTS_DIR" ]; then
    echo "" >> AGENTS.md
    echo "## Specialized Tasks" >> AGENTS.md
    echo "" >> AGENTS.md
    echo "Follow these instructions when the matching situation arises." >> AGENTS.md
    echo "" >> AGENTS.md

    for agent_file in "$AGENTS_DIR"/*.md; do
        [ -f "$agent_file" ] || continue

        # Extract description from frontmatter
        desc=$(grep '^description:' "$agent_file" | sed 's/^description: *//' | head -1)

        # Extract first paragraph of body (concise instructions, not full template)
        first_para=$(awk 'BEGIN{n=0} /^---/{n++; next} n>=2 && NF{p=1} p && !NF{exit} p{print}' "$agent_file")

        if [ -n "$first_para" ]; then
            echo "- **$desc** — $first_para" >> AGENTS.md
        fi
    done
fi

echo "Created: AGENTS.md"

# Optionally create .cursorrules (same content)
if command -v cursor &> /dev/null || [ -f .cursorrules ]; then
    cp AGENTS.md .cursorrules
    echo "Created: .cursorrules (same content)"
elif [ "$1" = "--cursor" ]; then
    cp AGENTS.md .cursorrules
    echo "Created: .cursorrules (same content)"
fi

# Count lines
lines=$(wc -l < AGENTS.md | tr -d ' ')
echo ""
echo "Done. $lines lines of universal agent rules."
echo "Works with: Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Aider, any LLM agent."
echo ""
echo "To also generate .cursorrules: $0 --cursor"