autonomous-coding-toolkit 1.0.0

package/hooks/stop-hook.sh

@@ -0,0 +1,135 @@
+#!/bin/bash
+
+# Ralph Loop Stop Hook
+# Prevents session exit when a ralph-loop is active
+# Feeds Claude's output back as input to continue the loop
+
+set -euo pipefail
+
+# Read hook input from stdin (advanced stop hook API)
+HOOK_INPUT=$(cat)
+
+# Check if ralph-loop is active
+RALPH_STATE_FILE=".claude/ralph-loop.local.md"
+
+if [[ ! -f "$RALPH_STATE_FILE" ]]; then
+  # No active loop - allow exit
+  exit 0
+fi
+
+# Parse markdown frontmatter (YAML between ---) and extract values
+FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$RALPH_STATE_FILE")
+ITERATION=$(echo "$FRONTMATTER" | grep '^iteration:' | sed 's/iteration: *//')
+MAX_ITERATIONS=$(echo "$FRONTMATTER" | grep '^max_iterations:' | sed 's/max_iterations: *//')
+# Extract completion_promise and strip surrounding quotes if present
+COMPLETION_PROMISE=$(echo "$FRONTMATTER" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/')
+
+# Validate numeric fields before arithmetic operations
+if [[ ! "$ITERATION" =~ ^[0-9]+$ ]]; then
+  echo "Ralph loop: State file corrupted (iteration not numeric)" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+if [[ ! "$MAX_ITERATIONS" =~ ^[0-9]+$ ]]; then
+  echo "Ralph loop: State file corrupted (max_iterations not numeric)" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Check if max iterations reached
+if [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then
+  echo "Ralph loop: Max iterations ($MAX_ITERATIONS) reached."
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Get transcript path from hook input
+TRANSCRIPT_PATH=$(echo "$HOOK_INPUT" | jq -r '.transcript_path')
+
+if [[ ! -f "$TRANSCRIPT_PATH" ]]; then
+  echo "Ralph loop: Transcript file not found" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Read last assistant message from transcript (JSONL format)
+if ! grep -q '"role":"assistant"' "$TRANSCRIPT_PATH"; then
+  echo "Ralph loop: No assistant messages found in transcript" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+LAST_LINE=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1)
+if [[ -z "$LAST_LINE" ]]; then
+  echo "Ralph loop: Failed to extract last assistant message" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Parse JSON with error handling
+LAST_OUTPUT=$(echo "$LAST_LINE" | jq -r '
+  .message.content |
+  map(select(.type == "text")) |
+  map(.text) |
+  join("\n")
+' 2>&1)
+
+if [[ $? -ne 0 ]]; then
+  echo "Ralph loop: Failed to parse assistant message JSON" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+if [[ -z "$LAST_OUTPUT" ]]; then
+  echo "Ralph loop: Assistant message contained no text content" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Check for completion promise (only if set)
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  PROMISE_TEXT=$(echo "$LAST_OUTPUT" | perl -0777 -pe 's/.*?<promise>(.*?)<\/promise>.*/$1/s; s/^\s+|\s+$//g; s/\s+/ /g' 2>/dev/null || echo "")
+
+  if [[ -n "$PROMISE_TEXT" ]] && [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
+    echo "Ralph loop: Detected <promise>$COMPLETION_PROMISE</promise>"
+    rm "$RALPH_STATE_FILE"
+    exit 0
+  fi
+fi
+
+# Not complete - continue loop with SAME PROMPT
+NEXT_ITERATION=$((ITERATION + 1))
+
+# Extract prompt (everything after the closing ---)
+PROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' "$RALPH_STATE_FILE")
+
+if [[ -z "$PROMPT_TEXT" ]]; then
+  echo "Ralph loop: State file corrupted (no prompt text)" >&2
+  rm "$RALPH_STATE_FILE"
+  exit 0
+fi
+
+# Update iteration in frontmatter
+TEMP_FILE="${RALPH_STATE_FILE}.tmp.$$"
+sed "s/^iteration: .*/iteration: $NEXT_ITERATION/" "$RALPH_STATE_FILE" > "$TEMP_FILE"
+mv "$TEMP_FILE" "$RALPH_STATE_FILE"
+
+# Build system message
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  SYSTEM_MSG="Ralph iteration $NEXT_ITERATION | To stop: output <promise>$COMPLETION_PROMISE</promise> (ONLY when statement is TRUE - do not lie to exit!)"
+else
+  SYSTEM_MSG="Ralph iteration $NEXT_ITERATION | No completion promise set - loop runs infinitely"
+fi
+
+# Output JSON to block the stop and feed prompt back
+jq -n \
+  --arg prompt "$PROMPT_TEXT" \
+  --arg msg "$SYSTEM_MSG" \
+  '{
+    "decision": "block",
+    "reason": $prompt,
+    "systemMessage": $msg
+  }'
+
+exit 0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "autonomous-coding-toolkit",
+  "version": "1.0.0",
+  "description": "Autonomous AI coding pipeline: quality gates, fresh-context execution, community lessons, and compounding learning",
+  "license": "MIT",
+  "author": "Justin McFarland <parthalon025@gmail.com>",
+  "homepage": "https://github.com/parthalon025/autonomous-coding-toolkit",
+  "repository": "https://github.com/parthalon025/autonomous-coding-toolkit",
+  "bin": {
+    "act": "./bin/act.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "skills/",
+    "commands/",
+    "agents/",
+    "hooks/",
+    "policies/",
+    "examples/",
+    "benchmarks/",
+    "docs/",
+    ".claude-plugin/",
+    "Makefile",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "keywords": [
+    "autonomous-coding",
+    "ai-agents",
+    "quality-gates",
+    "claude-code",
+    "tdd",
+    "lessons-learned",
+    "headless",
+    "multi-armed-bandit",
+    "code-review",
+    "pipeline"
+  ]
+}

package/policies/bash.md

@@ -0,0 +1,71 @@
+# Bash Policies
+
+Positive patterns for shell scripts. Derived from lessons #51, #58, #74, #75.
+
+## Strict Mode
+
+**Start every script with `set -euo pipefail`.**
+Without strict mode, failed commands are silently ignored and undefined variables expand to empty strings.
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+## Quote Variables
+
+**Always quote variable expansions.**
+Unquoted variables undergo word splitting and glob expansion, breaking on filespace names and special characters.
+
+```bash
+# Pattern: double-quote all expansions
+cp "$source_file" "$dest_dir/"
+if [[ -f "$config_path" ]]; then
+```
+
+## Subshell for Directory Changes
+
+**Use a subshell when `cd` is temporary.**
+Forgetting to `cd` back breaks all subsequent relative paths. A subshell automatically restores the working directory.
+
+```bash
+# Pattern: subshell isolates cd
+(
+    cd "$build_dir"
+    make install
+)
+# Back to original directory automatically
+```
+
+## Temp File Cleanup
+
+**Use `trap` to clean up temporary files.**
+Early exits from `set -e` skip manual cleanup. A trap ensures cleanup runs regardless of exit path.
+
+```bash
+tmpfile=$(mktemp)
+trap 'rm -f "$tmpfile"' EXIT
+
+# Use $tmpfile safely — cleanup guaranteed
+```
+
+## Redirect Then Move
+
+**Write to a temp file, then `mv` to the target.**
+Writing directly to the target risks corruption on failure — a partial write leaves an invalid file. `mv` is atomic on the same filesystem.
+
+```bash
+# Pattern: write to tmp, then atomic move
+jq '.count += 1' "$state_file" > "$tmp" && mv "$tmp" "$state_file"
+```
+
+## Arithmetic Evaluation
+
+**Use `$(( ))` for arithmetic, not bare expressions.**
+Shell arithmetic needs explicit evaluation context. Without it, expressions are treated as strings.
+
+```bash
+# Pattern: explicit arithmetic
+delta=$(( end_time - start_time ))
+if [[ $count -gt 0 ]]; then
+```

package/policies/python.md

@@ -0,0 +1,71 @@
+# Python Policies
+
+Positive patterns for Python codebases. Derived from lessons #25, #30, #33, #37, #43.
+
+## Async Discipline
+
+**Only use `async def` when the function performs I/O.**
+Unnecessary async adds complexity without benefit. If there's no `await` inside, it shouldn't be async.
+
+```python
+# Pattern: async def must contain await
+async def fetch_user(user_id: str) -> User:
+    return await db.get(user_id)  # I/O justifies async
+```
+
+## Await at Call Sites
+
+**Verify every call to an async function is awaited.**
+Missing `await` returns a coroutine object instead of the result — often passes truthiness checks silently.
+
+```python
+# Pattern: await at every async call site
+user = await fetch_user(user_id)  # not: user = fetch_user(user_id)
+```
+
+## SQLite Closing
+
+**Use `closing()` context manager for sqlite3 connections.**
+Without it, connections leak on exceptions. The `closing()` wrapper guarantees cleanup.
+
+```python
+from contextlib import closing
+import sqlite3
+
+with closing(sqlite3.connect("db.sqlite")) as conn:
+    cursor = conn.execute("SELECT ...")
+```
+
+## Task Error Visibility
+
+**Add a `done_callback` to every `create_task` call.**
+Unobserved task exceptions vanish silently. The callback surfaces errors immediately.
+
+```python
+task = asyncio.create_task(background_work())
+task.add_done_callback(lambda t: t.result() if not t.cancelled() else None)
+```
+
+## Subscriber Lifecycle
+
+**Store callback references on `self` and unsubscribe in `shutdown()`.**
+Anonymous lambda callbacks can't be unsubscribed. Leaked subscriptions cause duplicate processing after restart.
+
+```python
+class MyService:
+    def __init__(self, bus):
+        self._unsub = bus.subscribe("event", self._handle)
+
+    async def shutdown(self):
+        self._unsub()
+```
+
+## Install via Module
+
+**Use `.venv/bin/python -m pip` instead of `.venv/bin/pip`.**
+Direct pip invocation can resolve to Homebrew Python on mixed-runtime systems, installing packages into the wrong environment.
+
+```bash
+# Pattern: always invoke pip through python -m
+.venv/bin/python -m pip install pytest-xdist
+```

package/policies/testing.md

@@ -0,0 +1,61 @@
+# Testing Policies
+
+Positive patterns for test suites. Derived from lessons #32, #44, #50, #73, #78.
+
+## No Hardcoded Counts
+
+**Assert test behavior, not test quantities.**
+Hardcoded counts break when tests are added or removed. Count assertions create false failures unrelated to code quality.
+
+```bash
+# Pattern: assert threshold, not exact count
+test_count=$(pytest --co -q 2>/dev/null | tail -1 | grep -o '[0-9]*')
+[[ "$test_count" -ge 10 ]]  # not: [[ "$test_count" -eq 42 ]]
+```
+
+## Verify Threshold Math
+
+**Test boundary conditions explicitly.**
+Off-by-one errors in thresholds are the most common assertion bug. Test at, below, and above the boundary.
+
+```python
+# Pattern: test exact boundary
+assert is_valid(threshold)      # at boundary
+assert not is_valid(threshold - 1)  # below
+assert is_valid(threshold + 1)  # above (if applicable)
+```
+
+## Test the Test
+
+**Verify a test fails when the condition it checks is broken.**
+A test that always passes catches nothing. Temporarily break the code and confirm the test detects it.
+
+```bash
+# Pattern: red-green verification
+# 1. Write test → see it FAIL (red)
+# 2. Write code → see it PASS (green)
+# 3. Break code → see it FAIL again (confirms test works)
+```
+
+## Live Over Static
+
+**One live integration test catches more bugs than six static reviewers.**
+Static analysis finds structural issues but misses behavioral bugs. Always include at least one end-to-end test that exercises the real system.
+
+```bash
+# Pattern: combine static + live
+shellcheck scripts/*.sh          # static: catches syntax
+bash scripts/run-plan.sh --dry-run  # live: catches behavior
+```
+
+## Monotonic Test Count
+
+**Test counts only go up between batches.**
+A decreasing test count means something was deleted or broken. Track the high-water mark and enforce it.
+
+```bash
+# Pattern: compare against high-water mark
+prev_count=$(jq -r '.test_count' .run-plan-state.json)
+curr_count=$(pytest --co -q 2>/dev/null | tail -1 | grep -o '[0-9]*')
+[[ "$curr_count" -ge "$prev_count" ]]
+```

package/policies/universal.md

@@ -0,0 +1,60 @@
+# Universal Policies
+
+Cross-language positive patterns. These apply to all projects regardless of language.
+
+## Error Visibility
+
+**Always log before returning a fallback value.**
+When a function catches an error and returns a default, the error must be logged first. Silent fallbacks hide bugs.
+
+```
+# Pattern: catch → log → fallback
+try:
+    result = fetch_data()
+except ConnectionError as e:
+    logger.warning("fetch_data failed, using cache: %s", e)
+    result = cached_value
+```
+
+## Test Before Ship
+
+**Run the full test suite before claiming work is complete.**
+Partial test runs miss integration failures. "It works on my machine" is not verification.
+
+```
+# Pattern: test → verify → commit
+make ci          # or: pytest / npm test / make test
+git add <files>
+git commit
+```
+
+## Fresh Context Per Unit
+
+**Start each independent unit of work with a clean context.**
+Context degradation compounds — stale variables, wrong assumptions, and accumulated state cause subtle bugs after extended sessions.
+
+```
+# Pattern: checkpoint → clear → resume
+# After 5+ batches or major topic shift, start fresh
+```
+
+## Append-Only Progress
+
+**Never overwrite progress files — always append.**
+Truncating progress loses discoveries from prior batches. The next context reset will repeat mistakes.
+
+```
+# Pattern: append to progress.txt
+echo "## Batch 3: Added auth middleware" >> progress.txt
+```
+
+## Durable Artifacts
+
+**Every research activity produces a file, not just conversation.**
+Conversation context resets; files persist. If it's worth investigating, it's worth writing down.
+
+```
+# Pattern: investigate → write file → reference file
+# Bad: "I looked into it and found..."
+# Good: Write findings to tasks/research-<slug>.md
+```

package/scripts/analyze-report.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# analyze-report.sh — Analyze a report and pick the #1 actionable priority
+#
+# Usage: analyze-report.sh <report-file> [--dry-run] [--model MODEL]
+#
+# Reads a markdown report (test failures, errors, user feedback, metrics)
+# and uses an LLM to identify the single most impactful fix.
+#
+# Output: analysis.json with priority, reasoning, and suggested PRD outline
+#
+# Models: Uses Ollama queue (port 7683) for serialized execution.
+# Default model: deepseek-r1:8b (reasoning-optimized)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/common.sh"
+source "$SCRIPT_DIR/lib/ollama.sh"
+
+REPORT_FILE="${1:-}"
+DRY_RUN=false
+MODEL="deepseek-r1:8b"
+OUTPUT_DIR="."
+
+# Parse remaining args
+shift || true
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --dry-run) DRY_RUN=true; shift ;;
+    --model) MODEL="$2"; shift 2 ;;
+    --output-dir) OUTPUT_DIR="$2"; shift 2 ;;
+    *) echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+
+if [[ -z "$REPORT_FILE" ]] || [[ ! -f "$REPORT_FILE" ]]; then
+  echo "Usage: analyze-report.sh <report-file> [--dry-run] [--model MODEL]" >&2
+  echo "" >&2
+  echo "Report file not found: ${REPORT_FILE:-<none>}" >&2
+  exit 1
+fi
+
+REPORT_CONTENT=$(cat "$REPORT_FILE")
+
+PROMPT="You are analyzing a development report to identify the single most impactful priority to fix.
+
+## Report
+$REPORT_CONTENT
+
+## Instructions
+1. Read the report carefully
+2. Identify ALL issues mentioned
+3. Rank them by: revenue impact > user-facing bugs > developer experience > tech debt
+4. Pick the #1 priority — the one fix that delivers the most value
+
+## Output
+Respond with ONLY valid JSON (no markdown fences, no explanation):
+{
+  \"priority\": \"Short title of the #1 issue\",
+  \"reasoning\": \"Why this is #1 (2-3 sentences)\",
+  \"severity\": \"critical|high|medium|low\",
+  \"estimated_tasks\": 5,
+  \"prd_outline\": [
+    \"Task 1 title\",
+    \"Task 2 title\"
+  ]
+}"
+
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo "=== DRY RUN ==="
+  echo "Report: $REPORT_FILE"
+  echo "Model: $MODEL"
+  echo "Prompt length: ${#PROMPT} chars"
+  echo ""
+  echo "Would send to Ollama and save to $OUTPUT_DIR/analysis.json"
+  exit 0
+fi
+
+# Query Ollama (uses queue if available, falls back to direct)
+ANALYSIS=$(ollama_query "$MODEL" "$PROMPT")
+
+if [[ -z "$ANALYSIS" ]]; then
+  echo "Error: Empty response from Ollama" >&2
+  exit 1
+fi
+
+# Parse as JSON
+CLEANED=$(echo "$ANALYSIS" | ollama_extract_json)
+if [[ -n "$CLEANED" ]]; then
+    echo "$CLEANED" | jq . > "$OUTPUT_DIR/analysis.json"
+else
+    echo "Warning: Could not parse LLM response as JSON, saving raw" >&2
+    echo "{\"raw_response\": $(echo "$ANALYSIS" | jq -Rs .)}" > "$OUTPUT_DIR/analysis.json"
+fi
+
+echo "Analysis saved to $OUTPUT_DIR/analysis.json" >&2
+cat "$OUTPUT_DIR/analysis.json"

package/scripts/architecture-map.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# architecture-map.sh — Scan project for import/source dependencies → ARCHITECTURE-MAP.json
+#
+# Usage: architecture-map.sh [--project-root <dir>] [--help]
+#
+# Scans *.sh (source/. statements), *.py (import/from), *.js/*.ts (import/require).
+# Groups by directory into modules. Outputs JSON to docs/ARCHITECTURE-MAP.json.
+# Skips: node_modules, .git, __pycache__, .venv, .claude, .worktrees
+set -euo pipefail
+
+PROJECT_ROOT="."
+
+usage() {
+    cat <<'USAGE'
+architecture-map.sh — Scan project for dependency graph
+
+Usage: architecture-map.sh [--project-root <dir>] [--help]
+
+Outputs: docs/ARCHITECTURE-MAP.json
+
+Scans shell (source/.), Python (import/from), JS/TS (import/require) files.
+Groups files by directory into modules with dependency edges.
+USAGE
+}
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --help|-h) usage; exit 0 ;;
+            --project-root) PROJECT_ROOT="$2"; shift 2 ;;
+            *) echo "ERROR: Unknown option: $1" >&2; exit 1 ;;
+        esac
+    done
+}
+
+# Extract dependencies from a single file
+# Output: one dependency per line (relative path)
+extract_deps() {
+    local file="$1"
+    local ext="${file##*.}"
+
+    case "$ext" in
+        sh|bash)
+            # Match: source <path>, . <path>, source "<path>", . "<path>"
+            grep -oE '(source|\.)\s+"?[^"[:space:]]+"?' "$file" 2>/dev/null \
+                | sed -E 's/^(source|\.)\s+"?//; s/"?$//' \
+                | grep -v '^\$' || true  # Skip variable expansions
+            ;;
+        py)
+            # Match: from <module> import ..., import <module>
+            grep -oE '(from\s+\S+\s+import|^import\s+\S+)' "$file" 2>/dev/null \
+                | sed -E 's/^from\s+//; s/\s+import.*//; s/^import\s+//; s/\./\//g' \
+                | while IFS= read -r mod; do
+                    # Convert module path to file path
+                    if [[ -f "$PROJECT_ROOT/$mod.py" ]]; then
+                        echo "$mod.py"
+                    elif [[ -f "$PROJECT_ROOT/$mod/__init__.py" ]]; then
+                        echo "$mod/__init__.py"
+                    fi
+                done
+            ;;
+        js|ts|jsx|tsx)
+            # Match: import ... from '<path>', require('<path>')
+            grep -oE "(from\s+['\"][^'\"]+['\"]|require\(['\"][^'\"]+['\"]\))" "$file" 2>/dev/null \
+                | sed -E "s/from\s+['\"]//; s/require\(['\"]//; s/['\"].*//; s/\)$//" \
+                | grep -E '^\.' || true  # Only relative imports
+            ;;
+    esac
+}
+
+# Build the architecture map JSON
+build_map() {
+    local generated_at
+    generated_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+    # Find all relevant files, excluding common noise directories
+    local -a all_files=()
+    while IFS= read -r -d '' file; do
+        all_files+=("$file")
+    done < <(find "$PROJECT_ROOT" \
+        -not -path '*/.git/*' \
+        -not -path '*/node_modules/*' \
+        -not -path '*/__pycache__/*' \
+        -not -path '*/.venv/*' \
+        -not -path '*/.claude/*' \
+        -not -path '*/.worktrees/*' \
+        \( -name '*.sh' -o -name '*.py' -o -name '*.js' -o -name '*.ts' -o -name '*.jsx' -o -name '*.tsx' \) \
+        -print0 2>/dev/null | sort -z)
+
+    # Group files by directory (module)
+    declare -A modules
+
+    for file in "${all_files[@]}"; do
+        # Make path relative to project root
+        local rel_path="${file#"$PROJECT_ROOT/"}"
+        local dir
+        dir=$(dirname "$rel_path")
+        [[ "$dir" == "." ]] && dir="root"
+
+        # Extract dependencies
+        local deps=""
+        while IFS= read -r dep; do
+            [[ -z "$dep" ]] && continue
+            if [[ -n "$deps" ]]; then
+                deps+=","
+            fi
+            deps+="\"$dep\""
+        done < <(extract_deps "$file" | sort -u)
+
+        local file_json="{\"path\":\"$rel_path\",\"dependencies\":[$deps]}"
+
+        if [[ -n "${modules[$dir]:-}" ]]; then
+            modules["$dir"]+=","
+        fi
+        modules["$dir"]+="$file_json"
+    done
+
+    # Build modules array
+    local modules_json=""
+    for dir in $(echo "${!modules[@]}" | tr ' ' '\n' | sort); do
+        if [[ -n "$modules_json" ]]; then
+            modules_json+=","
+        fi
+        modules_json+="{\"name\":\"$dir\",\"files\":[${modules[$dir]}]}"
+    done
+
+    # Write output
+    local output_dir="$PROJECT_ROOT/docs"
+    mkdir -p "$output_dir"
+
+    cat > "$output_dir/ARCHITECTURE-MAP.json" <<JSON
+{
+  "generated_at": "$generated_at",
+  "project_root": "$(realpath "$PROJECT_ROOT")",
+  "modules": [$modules_json]
+}
+JSON
+
+    echo "Generated: $output_dir/ARCHITECTURE-MAP.json"
+    echo "  Modules: $(echo "${!modules[@]}" | wc -w | tr -d ' ')"
+    echo "  Files: ${#all_files[@]}"
+}
+
+parse_args "$@"
+build_map