@prateek_ai/agents-maker 1.0.0

package/quickstart.ps1

@@ -0,0 +1,252 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+    One-command setup for agents-maker on Windows.
+
+.DESCRIPTION
+    quickstart.ps1 — agents-maker bootstrap for Windows PowerShell
+
+    Usage (from your project root, with agents-maker\ cloned inside it):
+        .\agents-maker\quickstart.ps1
+        .\agents-maker\quickstart.ps1 -Update      # regenerate system_prompt.md
+        .\agents-maker\quickstart.ps1 -SkipInit    # skip init, just validate + show usage
+        .\agents-maker\quickstart.ps1 -NoColor     # plain output (CI/logging)
+
+    What it does:
+        1. Checks Python 3.9+ is available
+        2. Installs pyyaml (the only runtime dependency)
+        3. Runs tools\validate_kit.py to confirm the kit is intact
+        4. Runs tools\init_project.py to scan your project and generate system_prompt.md
+        5. Prints everything you need to run your first session
+
+.PARAMETER Update
+    Regenerate system_prompt.md even if it already exists.
+
+.PARAMETER SkipInit
+    Skip init_project.py — only install deps, validate, and show usage.
+
+.PARAMETER NoColor
+    Disable colored output (useful in CI or when piping to a file).
+#>
+
+param(
+    [switch]$Update,
+    [switch]$SkipInit,
+    [switch]$NoColor
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+
+# ---------------------------------------------------------------------------
+# Color helpers
+# ---------------------------------------------------------------------------
+function Write-Ok   { param([string]$Msg) Write-Colored "[OK]   " "Green"  $Msg }
+function Write-Info { param([string]$Msg) Write-Colored "[INFO] " "Cyan"   $Msg }
+function Write-Warn { param([string]$Msg) Write-Colored "[WARN] " "Yellow" $Msg }
+function Write-Fail { param([string]$Msg) Write-Colored "[FAIL] " "Red"    $Msg }
+
+function Write-Colored {
+    param([string]$Tag, [string]$Color, [string]$Msg)
+    if ($NoColor) {
+        Write-Host "$Tag $Msg"
+    } else {
+        Write-Host $Tag -ForegroundColor $Color -NoNewline
+        Write-Host " $Msg"
+    }
+}
+
+function Write-Step { param([string]$Msg)
+    Write-Host ""
+    if ($NoColor) { Write-Host "==> $Msg" }
+    else { Write-Host "==> $Msg" -ForegroundColor White }
+}
+
+function Write-Hr {
+    $line = "-" * 60
+    if ($NoColor) { Write-Host $line }
+    else { Write-Host $line -ForegroundColor Cyan }
+}
+
+# ---------------------------------------------------------------------------
+# Locate kit directory (the directory this script lives in)
+# ---------------------------------------------------------------------------
+$KitDir     = $PSScriptRoot
+$ProjectRoot = Split-Path $KitDir -Parent
+
+Write-Hr
+Write-Host "  agents-maker quickstart" -ForegroundColor White
+Write-Host "  Kit:     $KitDir"
+Write-Host "  Project: $ProjectRoot"
+Write-Hr
+
+# ---------------------------------------------------------------------------
+# Step 1 — Python version check
+# ---------------------------------------------------------------------------
+Write-Step "Step 1 - Checking Python"
+
+$PY = $null
+$candidates = @("python", "python3", "py")
+
+foreach ($candidate in $candidates) {
+    $found = Get-Command $candidate -ErrorAction SilentlyContinue
+    if (-not $found) { continue }
+
+    try {
+        $versionStr = & $candidate -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>$null
+        if ($LASTEXITCODE -ne 0) { continue }
+
+        $parts = $versionStr.Trim().Split(".")
+        $major = [int]$parts[0]
+        $minor = [int]$parts[1]
+
+        if ($major -ge 3 -and $minor -ge 9) {
+            $PY = $candidate
+            Write-Ok "Found Python $versionStr at $($found.Source)"
+            break
+        } else {
+            Write-Warn "Skipping $candidate ($versionStr) - need 3.9+"
+        }
+    } catch {
+        continue
+    }
+}
+
+if (-not $PY) {
+    Write-Fail "Python 3.9+ not found."
+    Write-Host "  Install from https://python.org, ensure 'Add Python to PATH' is checked, then re-run."
+    exit 1
+}
+
+# ---------------------------------------------------------------------------
+# Step 2 — Install dependencies
+# ---------------------------------------------------------------------------
+Write-Step "Step 2 - Installing dependencies"
+
+$ReqFile = Join-Path $KitDir "requirements.txt"
+if (-not (Test-Path $ReqFile)) {
+    Write-Fail "requirements.txt not found at $ReqFile"
+    exit 1
+}
+
+& $PY -m pip install -r $ReqFile --quiet
+if ($LASTEXITCODE -ne 0) {
+    Write-Fail "pip install failed. Try: $PY -m pip install pyyaml"
+    exit 1
+}
+Write-Ok "Dependencies installed (pyyaml)"
+
+# ---------------------------------------------------------------------------
+# Step 3 — Validate kit integrity
+# ---------------------------------------------------------------------------
+Write-Step "Step 3 - Validating kit integrity"
+
+$Validator = Join-Path $KitDir "tools\validate_kit.py"
+if (-not (Test-Path $Validator)) {
+    Write-Fail "tools\validate_kit.py not found - is the kit complete?"
+    exit 1
+}
+
+& $PY $Validator
+if ($LASTEXITCODE -ne 0) {
+    Write-Fail "Kit validation failed - see output above."
+    Write-Host ""
+    Write-Host "  If you modified agent or skill files, re-run validate_kit.py manually:"
+    Write-Host "    $PY agents-maker\tools\validate_kit.py"
+    exit 1
+}
+Write-Ok "All integrity checks passed"
+
+# ---------------------------------------------------------------------------
+# Step 4 — init_project.py
+# ---------------------------------------------------------------------------
+if (-not $SkipInit) {
+    Write-Step "Step 4 - Initializing project (generating system_prompt.md)"
+
+    $InitScript = Join-Path $KitDir "tools\init_project.py"
+    if (-not (Test-Path $InitScript)) {
+        Write-Fail "tools\init_project.py not found - is the kit complete?"
+        exit 1
+    }
+
+    Write-Host ""
+    $updateArg = if ($Update) { "--update" } else { "" }
+    Write-Info "Running: $PY $InitScript $updateArg --path $ProjectRoot"
+    Write-Info "You will be asked to confirm or override the detected domain."
+    Write-Host ""
+
+    if ($Update) {
+        & $PY $InitScript "--update" "--path" $ProjectRoot
+    } else {
+        & $PY $InitScript "--path" $ProjectRoot
+    }
+
+    if ($LASTEXITCODE -ne 0) {
+        Write-Fail "init_project.py failed - see output above."
+        exit 1
+    }
+    Write-Ok "init_project.py completed"
+} else {
+    Write-Step "Step 4 - Skipping init (-SkipInit)"
+    Write-Info "system_prompt.md was not regenerated."
+}
+
+# ---------------------------------------------------------------------------
+# Step 5 — Final summary and usage guide
+# ---------------------------------------------------------------------------
+$SystemPromptPath = Join-Path $KitDir "system_prompt.md"
+
+Write-Host ""
+Write-Hr
+Write-Host "  Setup complete. Here is everything you need to know." -ForegroundColor White
+Write-Hr
+Write-Host ""
+
+if (Test-Path $SystemPromptPath) {
+    $bytes  = (Get-Item $SystemPromptPath).Length
+    $tokens = [int]($bytes / 4)
+    Write-Ok "system_prompt.md  (~$bytes chars, ~$tokens tokens)"
+    Write-Host "  Paste it into your AI tool's system prompt / project instructions."
+    Write-Host "  You only need to do this once per AI context."
+} else {
+    Write-Warn "system_prompt.md was not created. Re-run without -SkipInit."
+}
+
+Write-Host ""
+Write-Host "  How to generate prompts" -ForegroundColor White
+Write-Host ""
+Write-Host "  Basic:"
+Write-Host "    $PY agents-maker\tools\generate_prompt.py `"describe your task here`""
+Write-Host ""
+Write-Host "  With phase:"
+Write-Host "    $PY agents-maker\tools\generate_prompt.py `"your task`" --phase implementation"
+Write-Host "    $PY agents-maker\tools\generate_prompt.py `"your task`" --phase review"
+Write-Host "    $PY agents-maker\tools\generate_prompt.py `"your task`" --phase solution_design"
+Write-Host ""
+Write-Host "  With token compression:"
+Write-Host "    $PY agents-maker\tools\generate_prompt.py `"your task`" --compress"
+Write-Host ""
+Write-Host "  With full system prompt (for models without persistent system prompt):"
+Write-Host "    $PY agents-maker\tools\generate_prompt.py `"your task`" --full"
+Write-Host ""
+Write-Host "  Valid phases: task_framing | requirements | solution_design |"
+Write-Host "                implementation | review_refinement | handoff"
+Write-Host ""
+Write-Host "  Context loaders (run and paste output with your task)" -ForegroundColor White
+Write-Host ""
+Write-Host "    $PY agents-maker\context_loaders\project_summary.py --path ."
+Write-Host "    $PY agents-maker\context_loaders\repo_tree.py --path ."
+Write-Host "    $PY agents-maker\context_loaders\file_chunker.py --path . --files src\main.py src\auth.py"
+Write-Host ""
+Write-Host "  Keeping system_prompt.md current" -ForegroundColor White
+Write-Host ""
+Write-Host "    .\agents-maker\quickstart.ps1 -Update"
+Write-Host "    # or: $PY agents-maker\tools\init_project.py --update"
+Write-Host ""
+Write-Host "  Validate any time" -ForegroundColor White
+Write-Host ""
+Write-Host "    $PY agents-maker\tools\validate_kit.py"
+Write-Host ""
+Write-Hr
+Write-Host ""

package/quickstart.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env bash
+# quickstart.sh — One-command setup for agents-maker
+#
+# Usage (from your project root, with agents-maker/ cloned inside it):
+#   bash agents-maker/quickstart.sh
+#   bash agents-maker/quickstart.sh --update     # regenerate system_prompt.md
+#   bash agents-maker/quickstart.sh --skip-init  # skip init, just validate + show usage
+#   bash agents-maker/quickstart.sh --no-color   # plain output (CI/logging)
+#
+# What it does:
+#   1. Checks Python 3.9+ is available
+#   2. Installs pyyaml (the only runtime dependency)
+#   3. Runs tools/validate_kit.py to confirm the kit is intact
+#   4. Runs tools/init_project.py to scan your project and generate system_prompt.md
+#   5. Prints everything you need to run your first session
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Arg parsing
+# ---------------------------------------------------------------------------
+UPDATE_FLAG=""
+SKIP_INIT=0
+NO_COLOR=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --update)     UPDATE_FLAG="--update" ;;
+    --skip-init)  SKIP_INIT=1 ;;
+    --no-color)   NO_COLOR=1 ;;
+    --help|-h)
+      # Print only the leading doc block (lines 2..first blank line)
+      tail -n +2 "$0" | while IFS= read -r line; do
+        [[ "$line" =~ ^# ]] || break
+        echo "${line#\# }" | sed 's/^#$//'
+      done
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $arg  (use --help for usage)" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Color helpers
+# ---------------------------------------------------------------------------
+if [[ $NO_COLOR -eq 0 && -t 1 ]]; then
+  GREEN="\033[0;32m"
+  YELLOW="\033[0;33m"
+  CYAN="\033[0;36m"
+  RED="\033[0;31m"
+  BOLD="\033[1m"
+  RESET="\033[0m"
+else
+  GREEN="" YELLOW="" CYAN="" RED="" BOLD="" RESET=""
+fi
+
+ok()   { echo -e "${GREEN}[OK]${RESET}    $*"; }
+info() { echo -e "${CYAN}[INFO]${RESET}  $*"; }
+warn() { echo -e "${YELLOW}[WARN]${RESET}  $*"; }
+fail() { echo -e "${RED}[FAIL]${RESET}  $*" >&2; }
+step() { echo -e "\n${BOLD}==> $*${RESET}"; }
+hr()   { echo -e "${CYAN}$(printf '%.0s─' {1..60})${RESET}"; }
+
+# ---------------------------------------------------------------------------
+# Locate kit directory (the directory this script lives in)
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+KIT_DIR="$SCRIPT_DIR"
+PROJECT_ROOT="$(dirname "$KIT_DIR")"
+
+hr
+echo -e "${BOLD}  agents-maker quickstart${RESET}"
+echo "  Kit:     $KIT_DIR"
+echo "  Project: $PROJECT_ROOT"
+hr
+
+# ---------------------------------------------------------------------------
+# Step 1 — Python version check
+# ---------------------------------------------------------------------------
+step "Step 1 — Checking Python"
+
+PY=""
+for candidate in python3 python python3.12 python3.11 python3.10 python3.9; do
+  if command -v "$candidate" &>/dev/null; then
+    version=$("$candidate" -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+    major="${version%%.*}"
+    minor="${version#*.}"
+    if [[ $major -ge 3 && $minor -ge 9 ]]; then
+      PY="$candidate"
+      ok "Found Python $version at $(command -v "$candidate")"
+      break
+    else
+      warn "Skipping $candidate ($version) — need 3.9+"
+    fi
+  fi
+done
+
+if [[ -z "$PY" ]]; then
+  fail "Python 3.9+ not found. Install from https://python.org and re-run."
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Step 2 — Install dependencies
+# ---------------------------------------------------------------------------
+step "Step 2 — Installing dependencies"
+
+REQ="$KIT_DIR/requirements.txt"
+if [[ ! -f "$REQ" ]]; then
+  fail "requirements.txt not found at $REQ"
+  exit 1
+fi
+
+if "$PY" -m pip install -r "$REQ" --quiet; then
+  ok "Dependencies installed (pyyaml)"
+else
+  fail "pip install failed. Try: $PY -m pip install pyyaml"
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Step 3 — Validate kit integrity
+# ---------------------------------------------------------------------------
+step "Step 3 — Validating kit integrity"
+
+VALIDATOR="$KIT_DIR/tools/validate_kit.py"
+if [[ ! -f "$VALIDATOR" ]]; then
+  fail "tools/validate_kit.py not found — is the kit complete?"
+  exit 1
+fi
+
+if "$PY" "$VALIDATOR"; then
+  ok "All integrity checks passed"
+else
+  fail "Kit validation failed — see output above."
+  echo ""
+  echo "  If you modified agent or skill files, re-run validate_kit.py manually:"
+  echo "    $PY agents-maker/tools/validate_kit.py"
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Step 4 — init_project.py
+# ---------------------------------------------------------------------------
+if [[ $SKIP_INIT -eq 0 ]]; then
+  step "Step 4 — Initializing project (generating system_prompt.md)"
+
+  INIT="$KIT_DIR/tools/init_project.py"
+  if [[ ! -f "$INIT" ]]; then
+    fail "tools/init_project.py not found — is the kit complete?"
+    exit 1
+  fi
+
+  echo ""
+  info "Running: $PY $INIT $UPDATE_FLAG --path $PROJECT_ROOT"
+  info "You will be asked to confirm or override the detected domain."
+  echo ""
+
+  # Run with --path so init_project.py scans the correct project root
+  if "$PY" "$INIT" $UPDATE_FLAG --path "$PROJECT_ROOT"; then
+    ok "init_project.py completed"
+  else
+    fail "init_project.py failed — see output above."
+    exit 1
+  fi
+else
+  step "Step 4 — Skipping init (--skip-init)"
+  info "system_prompt.md was not regenerated."
+fi
+
+# ---------------------------------------------------------------------------
+# Step 5 — Final summary and usage guide
+# ---------------------------------------------------------------------------
+SYSTEM_PROMPT="$KIT_DIR/system_prompt.md"
+
+echo ""
+hr
+echo -e "${BOLD}  Setup complete. Here is everything you need to know.${RESET}"
+hr
+echo ""
+
+# system_prompt.md status
+if [[ -f "$SYSTEM_PROMPT" ]]; then
+  CHARS=$(wc -c < "$SYSTEM_PROMPT" | tr -d ' ')
+  TOKENS=$(( CHARS / 4 ))
+  ok "system_prompt.md  (~${CHARS} chars, ~${TOKENS} tokens)"
+  echo "  Paste it into your AI tool's system prompt / project instructions."
+  echo "  You only need to do this once per AI context."
+else
+  warn "system_prompt.md was not created. Run init without --skip-init."
+fi
+
+echo ""
+echo -e "${BOLD}  How to generate prompts${RESET}"
+echo ""
+echo "  Basic:"
+echo "    $PY agents-maker/tools/generate_prompt.py \"describe your task here\""
+echo ""
+echo "  With phase:"
+echo "    $PY agents-maker/tools/generate_prompt.py \"your task\" --phase implementation"
+echo "    $PY agents-maker/tools/generate_prompt.py \"your task\" --phase review"
+echo "    $PY agents-maker/tools/generate_prompt.py \"your task\" --phase solution_design"
+echo ""
+echo "  With token compression:"
+echo "    $PY agents-maker/tools/generate_prompt.py \"your task\" --compress"
+echo ""
+echo "  With full system prompt (for models without persistent system prompt):"
+echo "    $PY agents-maker/tools/generate_prompt.py \"your task\" --full"
+echo ""
+echo "  Valid phases: task_framing | requirements | solution_design |"
+echo "                implementation | review_refinement | handoff"
+echo ""
+echo -e "${BOLD}  Context loaders (run these and paste the output with your task)${RESET}"
+echo ""
+echo "    $PY agents-maker/context_loaders/project_summary.py --path ."
+echo "    $PY agents-maker/context_loaders/repo_tree.py --path ."
+echo "    $PY agents-maker/context_loaders/file_chunker.py --path . --files src/main.py src/auth.py"
+echo ""
+echo -e "${BOLD}  Keeping system_prompt.md current${RESET}"
+echo ""
+echo "    bash agents-maker/quickstart.sh --update"
+echo "    # or: $PY agents-maker/tools/init_project.py --update"
+echo ""
+echo -e "${BOLD}  Validate any time${RESET}"
+echo ""
+echo "    $PY agents-maker/tools/validate_kit.py"
+echo ""
+hr
+echo ""

package/requirements.txt

@@ -0,0 +1,3 @@
+# agents-maker runtime dependency
+# Install: pip install -r agents-maker/requirements.txt
+pyyaml>=6.0,<8

package/skills/analyze_repo.md

@@ -0,0 +1,86 @@
+# Skill: analyze_repo
+
+## Description
+
+Walk a repository's file tree and produce a compact, structured summary of the project: detected stack, primary services or modules, main entrypoints, test structure, and key configuration files. Used by the Orchestrator and Architect Agent to build the Project State block at the start of a session.
+
+---
+
+## When to invoke
+
+- Session start, when no project summary is available.
+- When routing a task that requires understanding the broader project structure beyond the provided snippets.
+- When the Architect Agent needs a service map before designing a new component.
+
+---
+
+## Input expectations
+
+| Input | Required | Description |
+|---|---|---|
+| `repo_path` | Yes | Root path of the repository |
+| `filter_paths` | No | List of subdirectory prefixes to include (e.g., `src/`, `app/`, `services/`) |
+| `exclude_patterns` | No | Patterns to exclude (e.g., `node_modules/`, `__pycache__/`, `.git/`) |
+| `max_depth` | No | Maximum directory depth to traverse (default: 4) |
+
+In a conversational context, the user provides these via the `context_loaders/repo_tree.py` and `context_loaders/project_summary.py` scripts, and pastes the output.
+
+**If required input is missing:**
+- `repo_path` — if no path is provided and no repo context has been pasted, ask: "Please paste the output of `python agents-maker/context_loaders/repo_tree.py` or describe your project's directory structure." Do not produce a summary from nothing.
+- `filter_paths` — default to scanning the entire repo up to `max_depth`.
+- `exclude_patterns` — default to excluding `node_modules/`, `__pycache__/`, `.git/`, `dist/`, `build/`.
+- `max_depth` — default to 4.
+
+---
+
+## Output format
+
+The skill produces a structured text block:
+
+```
+## Project Summary
+
+**Stack**: <language(s), runtime version(s), primary framework(s)>
+**Build tool**: <e.g., pip + setuptools, npm + webpack, gradle>
+**Test framework**: <e.g., pytest, jest, JUnit>
+**Containerization**: <Docker | none | Kubernetes manifests present>
+
+## Services / Modules
+
+| Name | Path | Responsibility |
+|---|---|---|
+| <name> | <path> | <one-line description> |
+
+## Main Entrypoints
+
+| File | Purpose |
+|---|---|
+| <path> | <what it starts or exports> |
+
+## Key Config Files
+
+| File | Purpose |
+|---|---|
+| <path> | <what it configures> |
+
+## Test Structure
+
+| Path | Type | Coverage scope |
+|---|---|---|
+| <path> | unit | integration | e2e | <scope> |
+```
+
+---
+
+## Token cost tier
+
+**Medium.** Involves reading file tree and inspecting key files. Output is typically 300–600 tokens.
+
+Compression hint: the output is already compact. Do not summarize it further — it is the basis for all other context in the session.
+
+---
+
+## Notes
+
+- This skill is implemented as `context_loaders/project_summary.py`. In agent sessions without tool access, the user runs it locally and pastes the output.
+- If the repo has no recognizable structure, return the raw tree truncated at `max_depth` and note: "Could not detect stack — please specify language and framework manually."