autonomous-coding-toolkit 1.0.0

package/scripts/validate-prd.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# validate-prd.sh — Validate PRD JSON structure and references
+# Exit 0 if clean, exit 1 if violations found. Use --warn to print but exit 0.
+# Requires: jq
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PRD_FILE="${PRD_FILE:-$SCRIPT_DIR/../tasks/prd.json}"
+WARN_ONLY=false
+violations=0
+
+usage() {
+    echo "Usage: validate-prd.sh [--warn] [--help] [file]"
+    echo "  Validates PRD JSON file structure"
+    echo "  Without arguments, validates tasks/prd.json"
+    echo "  --warn   Print violations but exit 0"
+    exit 0
+}
+
+report_violation() {
+    local msg="$1"
+    echo "$(basename "$PRD_FILE"): ${msg}"
+    ((violations++)) || true
+}
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --help|-h) usage ;;
+        --warn) WARN_ONLY=true; shift ;;
+        *) PRD_FILE="$1"; shift ;;
+    esac
+done
+
+# Check jq is available
+if ! command -v jq &>/dev/null; then
+    echo "validate-prd: jq is required but not found" >&2
+    exit 1
+fi
+
+# Check file exists
+if [[ ! -f "$PRD_FILE" ]]; then
+    echo "validate-prd: PRD file not found: $PRD_FILE" >&2
+    exit 1
+fi
+
+# Check 1: Valid JSON
+if ! jq empty "$PRD_FILE" 2>/dev/null; then
+    report_violation "Invalid JSON (jq parse error)"
+    echo ""
+    echo "validate-prd: FAIL ($violations issues)"
+    [[ "$WARN_ONLY" == true ]] && exit 0
+    exit 1
+fi
+
+# Check 2: Must be a JSON array
+is_array=$(jq 'type == "array"' "$PRD_FILE")
+if [[ "$is_array" != "true" ]]; then
+    report_violation "Root must be a JSON array, got $(jq -r 'type' "$PRD_FILE")"
+    echo ""
+    echo "validate-prd: FAIL ($violations issues)"
+    [[ "$WARN_ONLY" == true ]] && exit 0
+    exit 1
+fi
+
+# Collect all valid IDs for reference checking
+all_ids=$(jq -r '.[].id // empty' "$PRD_FILE" 2>/dev/null | sort -n)
+
+# Check each element
+count=$(jq 'length' "$PRD_FILE")
+for ((i = 0; i < count; i++)); do
+    idx=$((i + 1))
+
+    # Check 3: id must be a number
+    id_type=$(jq -r ".[$i].id | type" "$PRD_FILE")
+    id_val=$(jq -r ".[$i].id // empty" "$PRD_FILE")
+    if [[ "$id_type" != "number" ]]; then
+        report_violation "Task $idx: missing or non-numeric 'id'"
+    fi
+
+    # Check 4: title must be a non-empty string
+    title=$(jq -r ".[$i].title // empty" "$PRD_FILE")
+    if [[ -z "$title" ]]; then
+        report_violation "Task $idx (id=$id_val): missing or empty 'title'"
+    fi
+
+    # Check 5: acceptance_criteria must be a non-empty array
+    ac_type=$(jq -r ".[$i].acceptance_criteria | type" "$PRD_FILE")
+    ac_len=$(jq ".[$i].acceptance_criteria | length" "$PRD_FILE" 2>/dev/null || echo 0)
+    if [[ "$ac_type" != "array" || "$ac_len" -eq 0 ]]; then
+        report_violation "Task $idx (id=$id_val): missing or empty 'acceptance_criteria'"
+    fi
+
+    # Check 6: blocked_by references must exist and not self-reference
+    if jq -e ".[$i].blocked_by" "$PRD_FILE" >/dev/null 2>&1; then
+        blocked_by=$(jq -r ".[$i].blocked_by[]?" "$PRD_FILE" 2>/dev/null || true)
+        for ref in $blocked_by; do
+            # Self-reference check
+            if [[ "$ref" == "$id_val" ]]; then
+                report_violation "Task $idx (id=$id_val): blocks itself"
+            fi
+            # Existence check
+            if ! echo "$all_ids" | grep -qx "$ref"; then
+                report_violation "Task $idx (id=$id_val): blocked_by references non-existent ID $ref"
+            fi
+        done
+    fi
+done
+
+if [[ $violations -gt 0 ]]; then
+    echo ""
+    echo "validate-prd: FAIL ($violations issues)"
+    [[ "$WARN_ONLY" == true ]] && exit 0
+    exit 1
+else
+    echo "validate-prd: PASS"
+    exit 0
+fi

package/scripts/validate-skills.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# validate-skills.sh — Validate skill directory structure and SKILL.md frontmatter
+# Exit 0 if clean, exit 1 if violations found. Use --warn to print but exit 0.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILLS_DIR="${SKILLS_DIR:-$SCRIPT_DIR/../skills}"
+WARN_ONLY=false
+violations=0
+
+usage() {
+    echo "Usage: validate-skills.sh [--warn] [--help]"
+    echo "  Validates all skills/*/SKILL.md files"
+    echo "  --warn   Print violations but exit 0"
+    exit 0
+}
+
+report_violation() {
+    local file="$1" line="$2" msg="$3"
+    echo "${file}:${line}: ${msg}"
+    ((violations++)) || true
+}
+
+[[ "${1:-}" == "--help" || "${1:-}" == "-h" ]] && usage
+[[ "${1:-}" == "--warn" ]] && WARN_ONLY=true
+
+if [[ ! -d "$SKILLS_DIR" ]]; then
+    echo "validate-skills: skills directory not found: $SKILLS_DIR" >&2
+    exit 1
+fi
+
+for skill_dir in "$SKILLS_DIR"/*/; do
+    [[ -d "$skill_dir" ]] || continue
+    dir_name="$(basename "$skill_dir")"
+    skill_file="$skill_dir/SKILL.md"
+
+    if [[ ! -f "$skill_file" ]]; then
+        report_violation "$dir_name" 0 "Missing SKILL.md"
+        continue
+    fi
+
+    # Check 1: First line must be ---
+    first_line=$(head -1 "$skill_file")
+    if [[ "$first_line" != "---" ]]; then
+        report_violation "$dir_name/SKILL.md" 1 "First line must be '---', got '$first_line'"
+        continue
+    fi
+
+    # Extract frontmatter (between first two --- lines)
+    frontmatter=$(sed -n '2,/^---$/{ /^---$/d; p; }' "$skill_file")
+
+    # Check 2: Required fields
+    for field in name description; do
+        if ! echo "$frontmatter" | grep -q "^${field}:"; then
+            report_violation "$dir_name/SKILL.md" 0 "Missing required field: $field"
+        fi
+    done
+
+    # Check 3: name must match directory name
+    skill_name=$(echo "$frontmatter" | sed -n 's/^name:[[:space:]]*\(.*\)/\1/p' | tr -d ' "'"'"'')
+    if [[ -n "$skill_name" && "$skill_name" != "$dir_name" ]]; then
+        report_violation "$dir_name/SKILL.md" 0 "name '$skill_name' does not match directory '$dir_name'"
+    fi
+
+    # Check 4: Referenced .md files in body must exist
+    # Body starts after the second ---
+    body=$(sed -n '/^---$/,$ p' "$skill_file" | tail -n +2)
+    body=$(echo "$body" | sed -n '/^---$/,$ p' | tail -n +2)
+    if [[ -n "$body" ]]; then
+        # Strip fenced code blocks and inline backtick-delimited content
+        # (paths like `docs/plans/foo.md`) — only bare .md refs are companion files
+        cleaned=$(echo "$body" | sed '/^```/,/^```/d' | sed 's/`[^`]*`//g')
+        referenced=$(echo "$cleaned" | grep -oE '[a-zA-Z0-9_-]+\.md' | sort -u || true)
+        for ref in $referenced; do
+            [[ "$ref" == "SKILL.md" ]] && continue
+            # Skip all-caps filenames (FRAMEWORK.md, SUMMARY.md, README.md, etc.)
+            # — these are conventional doc files that live outside the skill directory
+            if [[ "$ref" =~ ^[A-Z][A-Z0-9_-]*\.md$ ]]; then
+                continue
+            fi
+            if [[ ! -f "$skill_dir/$ref" ]]; then
+                report_violation "$dir_name/SKILL.md" 0 "Referenced file not found: $ref"
+            fi
+        done
+    fi
+done
+
+if [[ $violations -gt 0 ]]; then
+    echo ""
+    echo "validate-skills: FAIL ($violations issues)"
+    [[ "$WARN_ONLY" == true ]] && exit 0
+    exit 1
+else
+    echo "validate-skills: PASS"
+    exit 0
+fi

package/skills/autocode/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: autocode
+description: "Run the full autonomous coding pipeline — brainstorm → PRD → plan → execute → verify → finish — with Telegram notifications and quality gates at every stage."
+version: 1.0.0
+---
+
+# Autocode — Full Autonomous Coding Pipeline
+
+## Overview
+
+Orchestrate the complete agent-driven development pipeline from idea to merged code. This skill chains all stages in order, enforces hard gates between them, and optionally sends Telegram notifications at stage transitions.
+
+<HARD-GATE>
+Do NOT skip any stage. Do NOT proceed to the next stage until the current stage's exit criteria are met. Every stage must produce its required artifact before the gate opens.
+</HARD-GATE>
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Initialize pipeline** — detect project, set up Telegram, create progress.txt
+2. **Stage 0.5: Roadmap** (conditional) — invoke `autonomous-coding-toolkit:roadmap`, decompose multi-feature epic
+3. **Stage 1: Brainstorm** — invoke `autonomous-coding-toolkit:brainstorming`, produce approved design
+4. **Stage 1.5: Research** — invoke `autonomous-coding-toolkit:research`, investigate unknowns, produce research artifacts
+5. **Stage 2: PRD** — generate `tasks/prd.json` with machine-verifiable acceptance criteria
+6. **Stage 3: Plan** — invoke `autonomous-coding-toolkit:writing-plans`, produce batch plan
+7. **Stage 4: Execute** — run batches with quality gates, update PRD and progress.txt
+8. **Stage 5: Verify** — invoke `autonomous-coding-toolkit:verification-before-completion`, all PRD criteria pass
+9. **Stage 6: Finish** — invoke `autonomous-coding-toolkit:finishing-a-development-branch`, merge/PR/keep/discard
+
+## Arguments
+
+The user provides a feature description, report path, or issue reference:
+- Feature description: "Add user authentication with JWT"
+- Report path: `reports/daily.md` — run `scripts/analyze-report.sh` first to extract top priority
+- Issue: `#42` — fetch issue details via `gh issue view 42`
+
+## Pipeline
+
+### Stage 0: Initialize
+
+1. Detect the project: read `CLAUDE.md`, identify test command, linter, language
+2. Check for Telegram credentials:
+   ```bash
+   # Check if credentials exist (don't echo them)
+   grep -q 'TELEGRAM_BOT_TOKEN' ~/.env 2>/dev/null && echo "telegram: enabled" || echo "telegram: disabled"
+   ```
+3. If input is a report path, analyze it first:
+   ```bash
+   scripts/analyze-report.sh <report>
+   ```
+   Use the `#1 priority` from the analysis output as the feature description.
+4. Create or read `progress.txt` — append pipeline start entry
+5. Notify (if Telegram enabled):
+   ```
+   🏭 Autocode started: <feature summary>
+   Project: <name>
+   ```
+
+**Exit criteria:** Feature description is clear, project context loaded, progress.txt initialized.
+
+---
+
+### Stage 0.5: Roadmap (conditional)
+
+If the input describes multiple features (3+ distinct features, "roadmap" keyword, or an epic), invoke `autonomous-coding-toolkit:roadmap` to decompose it.
+
+This stage produces:
+- `tasks/roadmap.md` with dependency-ordered feature list
+- Phase groupings with effort estimates
+- User approval of feature ordering
+
+**Skip condition:** Single-feature inputs skip directly to Stage 1. When in doubt, check: does the input contain multiple independent deliverables?
+
+After roadmap approval, the pipeline loops through features in order — each feature runs Stages 1-6 independently.
+
+**Exit criteria:** `tasks/roadmap.md` exists and user approves feature ordering.
+
+**Telegram:** `✅ Stage 0.5 complete: Roadmap approved — <N> features, <M> phases`
+
+---
+
+### Stage 1: Brainstorm
+
+Invoke `autonomous-coding-toolkit:brainstorming` with the feature description.
+
+This stage produces:
+- Approved design doc at `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- User approval of the design
+
+**Exit criteria:** Design doc exists and user has approved it.
+
+**Telegram:** `✅ Stage 1 complete: Design approved — <title>`
+
+---
+
+### Stage 1.5: Research (conditional)
+
+After design approval, check if the feature involves technical unknowns, unfamiliar libraries, or integration with existing code. If so, invoke `autonomous-coding-toolkit:research`.
+
+This stage produces:
+- Research report at `tasks/research-<slug>.md`
+- Machine-readable findings at `tasks/research-<slug>.json`
+- Resolution of all blocking issues (or user override)
+
+**Skip condition:** If the brainstorming phase resolved all technical questions and no unknowns remain, this stage can be skipped. When in doubt, run it — 30 minutes of research prevents hours of rework.
+
+**Gate:** Run `scripts/research-gate.sh tasks/research-<slug>.json` — blocks if unresolved blocking issues exist. Use `--force` to override.
+
+**Exit criteria:** Research artifacts exist, research gate passes (or user overrides).
+
+**Telegram:** `✅ Stage 1.5 complete: Research done — <N> questions, <M> warnings`
+
+---
+
+### Stage 2: PRD Generation
+
+After design approval (and research if conducted), generate `tasks/prd.json` using the `/create-prd` format:
+- 8-15 granular tasks with machine-verifiable acceptance criteria
+- Every acceptance criterion is a shell command (exit 0 = pass)
+- Separate investigation tasks from implementation tasks
+- Order by dependency
+- Save both `tasks/prd.json` and `tasks/prd-<feature>.md`
+
+After generating, ask the user: **"How would you improve these acceptance criteria?"** — minimum 1 round of refinement.
+
+**Exit criteria:** `tasks/prd.json` exists, all criteria are shell commands, user approves.
+
+**Telegram:** `✅ Stage 2 complete: PRD generated — <N> tasks`
+
+---
+
+### Stage 3: Write Plan
+
+Invoke `autonomous-coding-toolkit:writing-plans` to create the implementation plan.
+
+Enhance the plan with:
+- A `## Quality Gates` section listing project-specific checks (auto-detect: `pytest`, `npm test`, `npm run lint`, `make test`, or `scripts/quality-gate.sh`)
+- Cross-references to `tasks/prd.json` task IDs in plan steps
+- `progress.txt` initialization as the first plan step
+- Plans with 3+ batches MUST include a final "Integration Wiring" batch
+
+**Exit criteria:** Plan file exists at `docs/plans/YYYY-MM-DD-<topic>.md`, user approves.
+
+**Telegram:** `✅ Stage 3 complete: Plan written — <N> batches, <M> tasks`
+
+---
+
+### Stage 4: Execute
+
+Ask the user which execution mode to use:
+
+| Mode | Best For | How |
+|------|----------|-----|
+| **In-session** | Small plans (1-3 batches) | Execute here with TDD |
+| **Subagent** | 5-15 independent tasks | `autonomous-coding-toolkit:subagent-driven-development` |
+| **Headless** | 4+ batches, unattended | `scripts/run-plan.sh <plan> --notify` |
+| **Ralph loop** | Iterate until done | `/ralph-loop` with completion promise |
+| **MAB** | Learn best strategy per batch type | `scripts/run-plan.sh <plan> --mab --notify` |
+
+#### For in-session and subagent modes:
+
+Between EVERY batch:
+1. Run quality gate:
+   ```bash
+   scripts/quality-gate.sh --project-root .
+   ```
+   If not available, run the project's test command directly.
+2. Update `tasks/prd.json` — set `"passes": true` for criteria that now pass
+3. Append batch summary to `progress.txt`
+4. Notify per batch:
+   ```
+   ✅ Batch <N>/<total>: <title>
+   Tests: <count> (↑<delta>) | <duration>
+   ```
+5. If quality gate fails: fix before proceeding. Notify:
+   ```
+   ❌ Batch <N>/<total> failed: <title>
+   Issue: <error summary>
+   ```
+
+#### For headless mode:
+
+Launch via bash:
+```bash
+scripts/run-plan.sh <plan-file> --notify --on-failure retry --max-retries 3 --verify
+```
+
+Report the command to the user and let them decide to run it.
+
+**Exit criteria:** All batches complete, all quality gates pass, test count monotonically increased.
+
+**Telegram:** `✅ Stage 4 complete: All <N> batches executed — <total tests> tests passing`
+
+---
+
+### Stage 5: Verify
+
+Invoke `autonomous-coding-toolkit:verification-before-completion`.
+
+Additionally:
+1. Run ALL acceptance criteria from `tasks/prd.json`:
+   ```bash
+   # For each criterion in prd.json
+   eval "<criterion_command>" && echo "PASS" || echo "FAIL"
+   ```
+2. Every task must have `"passes": true`
+3. Run lesson scanner against changed files
+4. For plans with 3+ batches: run A/B verification (see `ab-verification.md`)
+
+<HARD-GATE>
+Never claim completion if ANY PRD criterion fails. Fix failures and re-verify.
+</HARD-GATE>
+
+**Exit criteria:** All PRD criteria pass, verification evidence collected, no lesson violations.
+
+**Telegram:** `✅ Stage 5 complete: All <N> acceptance criteria passing`
+
+---
+
+### Stage 6: Finish
+
+Invoke `autonomous-coding-toolkit:finishing-a-development-branch`.
+
+After the user's choice (merge/PR/keep/discard):
+
+**Telegram:**
+- Merge: `🎉 Autocode complete: <feature> merged to <branch>`
+- PR: `🎉 Autocode complete: <feature> — PR #<N> created`
+- Keep: `📌 Autocode paused: <feature> on branch <name>`
+- Discard: `🗑️ Autocode cancelled: <feature> discarded`
+
+---
+
+## Telegram Notifications
+
+Notifications are sent via the Telegram Bot API using credentials from `~/.env`. They are **optional** — the pipeline works without them.
+
+To send a notification from within Claude Code:
+```bash
+TELEGRAM_BOT_TOKEN=$(grep 'TELEGRAM_BOT_TOKEN' ~/.env | cut -d= -f2-)
+TELEGRAM_CHAT_ID=$(grep 'TELEGRAM_CHAT_ID' ~/.env | cut -d= -f2-)
+curl -s -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
+  -d chat_id="$TELEGRAM_CHAT_ID" \
+  -d text="<message>" \
+  -d parse_mode="Markdown" \
+  --max-time 10 > /dev/null 2>&1
+```
+
+If credentials are missing, skip notifications silently — never block the pipeline on notification failure.
+
+## Rules
+
+- **Never skip a stage.** The design must be approved before PRD generation.
+- **Every acceptance criterion is a shell command.** No vague criteria.
+- **Quality gates run between EVERY batch**, not just at the end.
+- **Progress.txt is append-only** during execution — never truncate it.
+- **Test counts only go up.** If tests decrease, something broke — fix it.
+- **Notification failures are non-fatal.** Log and continue.
+- **Fresh context matters.** If past batch 5 in-session, suggest headless mode for remaining batches.
+
+## Common Mistakes
+
+**Skipping brainstorming for "simple" features**
+- Problem: Unexamined assumptions cause rework
+- Fix: Every feature goes through Stage 1, even one-line changes
+
+**Generating vague PRD criteria**
+- Problem: "Works correctly" is not verifiable
+- Fix: Every criterion is a shell command. `curl -s localhost:8080/api/health | jq -e '.status == "ok"'`
+
+**Proceeding past failed quality gates**
+- Problem: Cascading failures compound in later batches
+- Fix: Fix the gate failure BEFORE moving to the next batch
+
+**Not updating progress.txt**
+- Problem: Next batch (fresh context) loses discoveries
+- Fix: Append batch summary after every batch, before moving on
+
+## Integration
+
+**Called by:** User via `/autocode <feature>` or Skill tool
+**Calls:** brainstorming, writing-plans, executing-plans/subagent-driven-development, verification-before-completion, finishing-a-development-branch
+**State files:** `progress.txt`, `tasks/prd.json`, `.run-plan-state.json`
+**Scripts:** `scripts/run-plan.sh`, `scripts/quality-gate.sh`, `scripts/analyze-report.sh`

package/skills/autocode/ab-verification.md

@@ -0,0 +1,51 @@
+# A/B Verification
+
+Post-completion dual-axis verification for plans with 3+ batches. Catches non-overlapping bug classes that neither strategy alone finds.
+
+## When to Run
+
+After ALL batches are complete, regardless of execution mode. Cost: ~5 minutes, 2 agent runs.
+
+## Process
+
+Dispatch TWO verification agents in parallel:
+
+### Verifier A (Systematic / Bottom-Up)
+
+subagent_type=general-purpose
+
+Check:
+- File sizes: flag any file over 300 lines (Python or JSX)
+- Test coverage gaps: modules with no corresponding test file
+- Anti-patterns: bare `except`, silent `return []`, `sqlite3.connect()` without `closing()`
+- Dead config keys: keys registered in config_defaults but never consumed via `get_config_value()`
+- Import health: circular imports, unused imports, duplicate exports
+- Metrics: total test count, ruff/lint clean, file count by type
+
+### Verifier B (Holistic / Top-Down)
+
+subagent_type=general-purpose
+
+Check:
+- Integration boundaries: trace data from producer → consumer, verify key names match
+- Module lifecycle: `__init__` vs `initialize()` discipline, subscribe/unsubscribe pairing
+- Data flow: follow one real input through every layer to the final output
+- Security: no secrets, no hardcoded IPs, no debug artifacts
+- Dashboard cohesion: frontend props match backend response keys, shared constants not duplicated
+
+## Report Format
+
+```
+A/B VERIFICATION — [date]
+Verifier A (bottom-up): [N] critical, [N] important, [N] minor
+Verifier B (top-down): [N] critical, [N] important, [N] minor
+Overlap: [N] (should be 0)
+Combined critical issues: [list]
+Combined important issues: [list]
+```
+
+## Rules
+
+- If ANY critical issues found: fix them before proceeding to finishing-a-development-branch
+- Create fix tasks, implement, re-run affected tests
+- Save report to `.ab-verification-report.md`

package/skills/autocode/code-quality-standards.md

@@ -0,0 +1,37 @@
+# Code Quality Standards
+
+Shared quality standards injected into all competitor and implementer prompts. Referenced by competitive-mode.md and team-mode implementer prompts.
+
+## File Size & Modularity
+
+- Target ~300 lines per file MAX. If a file exceeds 300 lines, split it into focused modules.
+- Each file should have ONE clear responsibility. If you can't describe the file's purpose in one sentence, it's doing too much.
+- Extract logical groups into separate files: constants → constants.py, helpers → helpers.py, types → models.py.
+- Functions should be short (under 30 lines). If a function needs a comment saying "Step 1... Step 2...", extract each step into a named function.
+- Prefer composition over inheritance. Small, focused functions that compose together.
+- For frontend: one component per file. Shared hooks/utilities in separate files. If a JSX file exceeds 300 lines, extract sub-components into their own files.
+
+## Code Cohesion
+
+Your code must look like ONE author wrote the whole codebase:
+
+- BEFORE writing anything: read 2-3 existing files in the same package to absorb the project's style — naming conventions, docstring format, import ordering, error handling patterns, logging style.
+- Match existing patterns EXACTLY: if the codebase uses `logger = logging.getLogger(__name__)`, do the same. If it uses `from __future__ import annotations`, include it. If functions use type hints, yours must too.
+- Naming: follow the codebase's conventions. `_private_helper()` with leading underscore, `UPPER_SNAKE` for module constants, `CamelCase` for classes.
+- Imports: group and order (stdlib → third-party → local). Use absolute imports (`from aria.x import Y`).
+- Error handling: follow codebase patterns. `logger.warning()` before returning fallback — never bare `except: pass`. Use specific exception types.
+- Docstrings: match existing format. One-line for simple helpers, multi-line for complex functions.
+- File structure: constants at top, public API in middle, private helpers at bottom.
+- DRY: check if utilities exist before writing new ones. Search shared modules, utils directories, sibling modules.
+- YAGNI: implement exactly what the spec requires. No extra config options, no "future-proofing" abstractions.
+- Frontend: match existing component patterns — same hook usage, prop naming, CSS classes, state management. Read sibling pages before writing.
+
+## Best Practices
+
+- Type hints on all function signatures (args and return).
+- Guard clauses over nested conditionals. Return early.
+- Descriptive variable names — no single-letter variables except loop counters.
+- No magic numbers — extract to named constants.
+- Errors should be logged with context before being handled: `logger.warning("Failed to X for entity %s: %s", entity_id, err)`.
+- Tests: one test function per behavior. Descriptive test names: `test_returns_empty_list_when_no_entities`.
+- Avoid deep nesting (>3 levels). Extract inner logic into helper functions.