azcodr 1.0.0

package/.agents/skills/lets-build/references/project_readme_template.md

@@ -0,0 +1,79 @@
+# {{PROJECT_NAME}}
+
+> **{{PROJECT_TAGLINE_OR_MISSION}}**
+
+---
+
+## 🌟 Architecture & Stack
+
+- **Architecture:** Hexagonal (Ports & Adapters) with strict systemic atomicity and zero-downtime database patterns.
+- **Language & Runtime:** {{LANGUAGE_AND_RUNTIME}}
+- **Package Manager & Build:** {{PACKAGE_MANAGER_AND_BUILD_TOOL}}
+- **Primary Transport:** {{TRANSPORT_PROTOCOL_AND_FRAMEWORK}}
+- **Persistence Engine:** {{DATABASE_ENGINE}} (Migrations via {{MIGRATION_TOOL}})
+- **Multi-Tenancy Isolation:** {{TENANCY_ISOLATION_MODEL}}
+- **Dynamic Extensibility:** Common Expression Language (CEL) / JSON Schema Draft 2020-12
+- **Observability:** OpenTelemetry (OTel) OTLP export over gRPC/HTTP
+- **Security & DevSecOps:** Semgrep SAST, Gitleaks, Trivy scanning, CycloneDX SBOM
+
+---
+
+## 🗂️ Project Structure
+
+```
+.
+├── specs/                            # Canonical contract specifications
+│   ├── openapi/                      # OpenAPI 3.1 REST specifications
+│   ├── protobuf/                     # Protocol Buffers v3 definitions
+│   ├── schemas/                      # Universal JSON Schema Draft 2020-12
+│   └── tokens/                       # W3C DTCG Design Tokens
+├── src/                              # Hexagonal Application Source
+│   ├── domain/                       # Core Invariant Domain (Entities, Value Objects)
+│   ├── ports/                        # Primary (Use Cases) and Secondary (Repositories) Ports
+│   └── adapters/                     # Ingress (HTTP/gRPC) and Egress (SQL/Broker) Adapters
+├── tests/
+│   ├── unit/                         # Fast unit tests using test doubles
+│   ├── integration/                  # Adapter tests with transactional rollback
+│   ├── contracts/                    # Consumer contract tests (Pact)
+│   └── acceptance/                   # BDD Gherkin / Cucumber features
+├── deploy/                           # OCI Distroless Dockerfiles & Compose manifests
+├── docs/rules/                       # 41 atomic single-responsibility architectural rules
+├── memory.md                         # Master memory hub & Lightweight ADR ledger
+└── AGENTS.md                         # Lean agentic directives (< 120 lines)
+```
+
+---
+
+## ⚡ Quickstart & Development
+
+### 1. Prerequisites
+- {{PREREQUISITES_LIST}}
+- Docker & Docker Compose
+
+### 2. Environment Setup
+```bash
+cp .env.example .env
+```
+
+### 3. Install Dependencies
+```bash
+{{INSTALL_COMMAND}}
+```
+
+### 4. Run Development Environment
+```bash
+{{DEV_RUN_COMMAND}}
+```
+
+### 5. Run Tests & Verification
+```bash
+{{TEST_COMMAND}}
+```
+
+---
+
+## 🏛️ Architecture Governance & Decisions
+
+This project is governed by the **41 Atomic Domain Rules** located in [`docs/rules/`](./docs/rules/) and Architectural Decision Records in [`memory.md`](./memory.md):
+- **ADR Ledger:** See [`memory.md`](./memory.md) for ADR-001 through ADR-006.
+- **Architectural Rules:** See [`docs/rules/`](./docs/rules/) for TDD, Clean Code, Multi-Tenancy, Database Integrity, and DevSecOps directives.

package/.agents/skills/lets-build/scripts/bootstrap_workspace.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# bootstrap_workspace.sh
+# Deterministic Scaffolder for Hexagonal Multi-Tenant Workspaces
+# ==============================================================================
+
+set -euo pipefail
+
+WORKSPACE_ROOT="${1:-$(pwd)}"
+LANGUAGE="${2:-generic}"
+
+echo "🚀 Initializing Hexagonal Architecture Workspace in: ${WORKSPACE_ROOT}"
+echo "📦 Target Language Profile: ${LANGUAGE}"
+echo "--------------------------------------------------------------"
+
+# 1. Create Universal Specification Directories
+echo "1. Scaffolding Contract Specification Directories (specs/)..."
+mkdir -p "${WORKSPACE_ROOT}/specs/protobuf"
+mkdir -p "${WORKSPACE_ROOT}/specs/openapi"
+mkdir -p "${WORKSPACE_ROOT}/specs/schemas"
+mkdir -p "${WORKSPACE_ROOT}/specs/tokens"
+
+# 2. Create Universal Hexagonal Source Directories
+echo "2. Scaffolding Hexagonal Source Tree (src/)..."
+mkdir -p "${WORKSPACE_ROOT}/src/domain/entities"
+mkdir -p "${WORKSPACE_ROOT}/src/domain/value_objects"
+mkdir -p "${WORKSPACE_ROOT}/src/domain/services"
+mkdir -p "${WORKSPACE_ROOT}/src/ports/primary"
+mkdir -p "${WORKSPACE_ROOT}/src/ports/secondary"
+mkdir -p "${WORKSPACE_ROOT}/src/adapters/primary"
+mkdir -p "${WORKSPACE_ROOT}/src/adapters/secondary"
+
+# 3. Create Universal Test Directories
+echo "3. Scaffolding Test Suites (tests/)..."
+mkdir -p "${WORKSPACE_ROOT}/tests/unit"
+mkdir -p "${WORKSPACE_ROOT}/tests/integration"
+mkdir -p "${WORKSPACE_ROOT}/tests/contracts"
+mkdir -p "${WORKSPACE_ROOT}/tests/acceptance"
+
+# 4. Create Deployment & Infrastructure Directories
+echo "4. Scaffolding Deployment Infrastructure (deploy/)..."
+mkdir -p "${WORKSPACE_ROOT}/deploy/docker"
+mkdir -p "${WORKSPACE_ROOT}/deploy/compose"
+mkdir -p "${WORKSPACE_ROOT}/deploy/k8s"
+
+# 5. Create Default Design Tokens Spec
+TOKEN_SPEC="${WORKSPACE_ROOT}/specs/tokens/tokens.json"
+if [[ ! -f "${TOKEN_SPEC}" ]]; then
+  cat << 'EOF' > "${TOKEN_SPEC}"
+{
+  "color": {
+    "brand": {
+      "primary": { "$value": "#2563eb", "$type": "color" },
+      "secondary": { "$value": "#475569", "$type": "color" },
+      "accent": { "$value": "#f59e0b", "$type": "color" }
+    }
+  },
+  "dimension": {
+    "radius": {
+      "base": { "$value": "6px", "$type": "dimension" }
+    }
+  }
+}
+EOF
+fi
+
+echo "--------------------------------------------------------------"
+echo "✅ Hexagonal directory tree and contract specifications scaffolded successfully!"

package/.agents/skills/merge-ai/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: merge-ai
+description: Use when the user invokes /merge-ai or asks to merge generic AI rules, skills, lessons learned, and post-mortems from the current workspace back into the generic azcodr baseline repository. Do not use for merging application business logic or routine Git branches.
+---
+
+# Merge AI Knowledge, Rules & Skills Skill (`/merge-ai`)
+
+> **Core Philosophy:** Upstream baseline repositories (e.g. `https://github.com/org/azcodr`) must remain pristine, generic, and untouched until the user explicitly triggers `/merge-ai`. When triggered from any project workspace (e.g. `https://github.com/org/my-project`), detect if the baseline repo is already cloned locally (apply directly) or clone it first, purge all project-specific domain models, colocate DOs and DONTs into atomic rules, and synchronize the generic baseline.
+
+---
+
+## 1. When to Use This Skill
+- The user issues `/merge-ai` or requests syncing AI rules, skills, issue logs, and lessons learned back into the generic baseline repository.
+- User references repository URLs (e.g. Source: `https://github.com/org/my-project`, Target: `https://github.com/org/azcodr`).
+- Auditing divergences between the current project workspace and the generic baseline repository.
+- Exporting newly discovered architectural patterns, defect post-mortems, or reusable skills to the generic starter.
+- **DO NOT USE** during routine project feature development or bug fixes.
+- **DO NOT USE** to merge application domain entities, business logic, or project-specific data models.
+- **DO NOT USE** without explicit user invocation.
+
+---
+
+## 2. Step-by-Step Execution Workflow
+
+### Phase 1: Target Baseline Repository Resolution (URL or Local)
+When `/merge-ai` is triggered with repository URLs (e.g. `/merge-ai https://github.com/org/my-project https://github.com/org/azcodr`):
+1. **Execute Repo Resolver Script:**
+   ```bash
+   # Discovers existing local clone or automatically clones fresh
+   eval $(bash .agents/skills/merge-ai/scripts/resolve_repo.sh "$TARGET_REPO_URL")
+   ```
+   - **If already cloned locally:** Discovers its directory, verifies clean working tree, and exports `STATUS=ALREADY_CLONED` and `LOCAL_PATH` (e.g. `/path/to/azcodr`).
+   - **If not cloned locally:** Automatically executes `git clone "$TARGET_REPO_URL"` to `$HOME/projects/<name>` and exports `STATUS=CLONED_FRESH` and `LOCAL_PATH`.
+2. Set `$BASELINE_DIR="$LOCAL_PATH"`.
+3. If `STATUS=ALREADY_CLONED`, ensure the repository is on branch `main` (`git -C "$BASELINE_DIR" pull --ff-only`).
+
+---
+
+### Phase 2: Divergence Audit & Domain Purging
+1. Run the divergence audit script:
+   ```bash
+   bash .agents/skills/merge-ai/scripts/audit_divergence.sh "$BASELINE_DIR"
+   ```
+2. Systematically filter out all project-specific elements before proposing changes:
+   - **Purge Business Domain Entities:** Replace project-specific nouns with universal architectural archetypes (`Entity`, `Aggregate`, `ValueObject`, `Resource`, `Transaction`).
+   - **Purge Concrete Stack Specifics:** Keep core rules stack-agnostic (Hexagonal Ports, abstract repositories). Keep project-specific setups (e.g. SQLite dev / Postgres prod, React Vite client) in the project workspace.
+   - **Colocate DOs & DONTs into Atomic Rules:** Embed DOs and DONTs directly inside their governing atomic rule files in `docs/rules/` (`## Invariants, DO's & DONT's`). Keep `docs/knowledge/dos_and_donts.md` strictly as a clean cross-reference index directory.
+   - **Transform ADRs & Post-Mortems:** Port universal decisions (ADR-007 CRUD & Selectors, ADR-008 Bootstrapping Decoupling, ADR-009 Agile Domain TDD, ADR-010 M:N Skill Composability) as generic ADRs in `memory.md`. Port universal post-mortems (`ISSUE-004`, `ISSUE-005`) into `issue_log.md` and `lessons_learned.md`.
+
+---
+
+### Phase 3: Dry-Run Review & Explicit User Confirmation
+1. Present a concise, structured dry-run report to the user summarizing:
+   - Target baseline repo URL and resolved local directory (`$BASELINE_DIR`).
+   - Generic rules, skills, post-mortems, and ADRs to be merged.
+   - Domain-specific elements purged.
+2. **STOP AND ASK FOR EXPLICIT CONFIRMATION** before modifying `$BASELINE_DIR`.
+
+---
+
+### Phase 4: Apply Merge, Validate & Sync
+Upon user confirmation:
+1. Apply the generic updates to `$BASELINE_DIR`:
+   - `AGENTS.md` (Unified Agent Cognitive & Agile Domain Lifecycle).
+   - `docs/rules/` (Updated atomic rules with colocated DOs/DONTs).
+   - `.agents/skills/` (Updated generic skills, e.g. decoupled `lets-build`).
+   - `docs/knowledge/` (Index-only `dos_and_donts.md`, generic post-mortems in `issue_log.md`, `lessons_learned.md`, `knowledge_graph.md`).
+   - `memory.md` (Generic ADRs).
+2. Validate agentic configuration integrity in the baseline:
+   ```bash
+   bash "$BASELINE_DIR/.agents/skills/agentic-architect/scripts/validate_agentic_configs.sh"
+   ```
+   *Requirement: 0 warnings, AGENTS.md <= 120 lines, valid symlinks.*
+3. Commit and push the baseline repository to remote:
+   ```bash
+   git -C "$BASELINE_DIR" add -A
+   git -C "$BASELINE_DIR" commit -m "feat(ai-sync): merge generic rules, skills, and lifecycle improvements from workspace"
+   git -C "$BASELINE_DIR" push origin main
+   ```
+4. Confirm successful synchronization with the remote generic baseline URL.
+
+---
+
+## 3. Gotchas & What NOT to Do
+
+- **MAJOR DONT: Never touch, edit, or commit to the baseline repository (`azcodr`) during routine feature development.** The baseline must be left completely alone until `/merge-ai` is explicitly invoked.
+- **DO NOT** copy application domain models, database tables, or framework-specific configs to the baseline.
+- **DO NOT** create monolithic DO/DONT lists. Always colocate directives in atomic rules.
+- **DO NOT** execute the merge without presenting a dry-run summary and receiving explicit approval.
+- **DO NOT** push to the baseline repository if `validate_agentic_configs.sh` fails or reports warnings.

package/.agents/skills/merge-ai/scripts/audit_divergence.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASELINE_DIR="${1:-/home/prosubodh/projects/azcodr}"
+CURRENT_DIR="$(pwd)"
+
+echo "=================================================================="
+echo "🔍 Auditing AI Knowledge & Rule Divergence"
+echo "Current Workspace: $CURRENT_DIR"
+echo "Baseline Template: $BASELINE_DIR"
+echo "=================================================================="
+
+if [ ! -d "$BASELINE_DIR" ]; then
+  echo "❌ Error: Baseline directory '$BASELINE_DIR' does not exist."
+  exit 1
+fi
+
+echo ""
+echo "--- 1. Checking Core Directives (AGENTS.md) ---"
+if diff -q "$CURRENT_DIR/AGENTS.md" "$BASELINE_DIR/AGENTS.md" > /dev/null 2>&1; then
+  echo "✅ AGENTS.md is identical."
+else
+  echo "⚠️ AGENTS.md differs between workspaces."
+fi
+
+echo ""
+echo "--- 2. Checking Atomic Rules (docs/rules/) ---"
+DIFF_RULES=$(diff -qr "$CURRENT_DIR/docs/rules" "$BASELINE_DIR/docs/rules" 2>/dev/null || true)
+if [ -z "$DIFF_RULES" ]; then
+  echo "✅ All atomic rules in docs/rules/ are identical."
+else
+  echo "$DIFF_RULES"
+fi
+
+echo ""
+echo "--- 3. Checking Specialized Skills (.agents/skills/) ---"
+DIFF_SKILLS=$(diff -qr "$CURRENT_DIR/.agents/skills" "$BASELINE_DIR/.agents/skills" 2>/dev/null || true)
+if [ -z "$DIFF_SKILLS" ]; then
+  echo "✅ All skills in .agents/skills/ are identical."
+else
+  echo "$DIFF_SKILLS"
+fi
+
+echo ""
+echo "--- 4. Checking Knowledge Hub (docs/knowledge/) ---"
+DIFF_KNOW=$(diff -qr "$CURRENT_DIR/docs/knowledge" "$BASELINE_DIR/docs/knowledge" 2>/dev/null || true)
+if [ -z "$DIFF_KNOW" ]; then
+  echo "✅ All knowledge files in docs/knowledge/ are identical."
+else
+  echo "$DIFF_KNOW"
+fi
+
+echo ""
+echo "--- 5. Checking Architecture Decision Records (memory.md) ---"
+if [ -f "$CURRENT_DIR/memory.md" ] && [ -f "$BASELINE_DIR/memory.md" ]; then
+  mapfile -t BASELINE_ADRS < <(grep -E '^### ADR-[0-9]+:' "$BASELINE_DIR/memory.md" 2>/dev/null | sed -E 's/^### ADR-[0-9]+:[[:space:]]*//' || true)
+  mapfile -t CURRENT_ADRS < <(grep -E '^### ADR-[0-9]+:' "$CURRENT_DIR/memory.md" 2>/dev/null | sed -E 's/^### ADR-[0-9]+:[[:space:]]*//' || true)
+
+  MISSING_IN_CURRENT=()
+  for b_adr in "${BASELINE_ADRS[@]}"; do
+    [ -z "$b_adr" ] && continue
+    found=false
+    for c_adr in "${CURRENT_ADRS[@]}"; do
+      if [ "$b_adr" = "$c_adr" ]; then
+        found=true
+        break
+      fi
+    done
+    if [ "$found" = false ]; then
+      MISSING_IN_CURRENT+=("$b_adr")
+    fi
+  done
+
+  EXTRA_IN_CURRENT=()
+  for c_adr in "${CURRENT_ADRS[@]}"; do
+    [ -z "$c_adr" ] && continue
+    found=false
+    for b_adr in "${BASELINE_ADRS[@]}"; do
+      if [ "$c_adr" = "$b_adr" ]; then
+        found=true
+        break
+      fi
+    done
+    if [ "$found" = false ]; then
+      EXTRA_IN_CURRENT+=("$c_adr")
+    fi
+  done
+
+  if [ ${#MISSING_IN_CURRENT[@]} -gt 0 ]; then
+    echo "⚠️ Workspace is missing ${#MISSING_IN_CURRENT[@]} baseline ADR(s):"
+    for m in "${MISSING_IN_CURRENT[@]}"; do
+      echo "   - $m"
+    done
+  elif [ ${#EXTRA_IN_CURRENT[@]} -eq 0 ]; then
+    echo "✅ memory.md ADRs are 100% identical."
+  else
+    echo "✅ All generic baseline ADRs are synchronized."
+    for e in "${EXTRA_IN_CURRENT[@]}"; do
+      echo "   ℹ️ Project-specific ADR retained in workspace: $e"
+    done
+  fi
+else
+  echo "⚠️ memory.md not found in one or both workspaces."
+fi
+
+echo "=================================================================="
+echo "Audit complete. Run /merge-ai to filter and merge generic changes."
+echo "=================================================================="

package/.agents/skills/merge-ai/scripts/resolve_repo.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ==============================================================================
+# resolve_repo.sh
+# Deterministically resolves whether a remote Git URL is cloned locally,
+# EVEN IF CLONED UNDER A COMPLETELY DIFFERENT FOLDER NAME.
+#
+# Usage: ./resolve_repo.sh <REPO_URL> [--check-only] [--dest-dir <DIR>]
+# ==============================================================================
+
+REPO_URL="${1:-}"
+CHECK_ONLY=false
+DEST_DIR=""
+
+if [ -z "$REPO_URL" ]; then
+  echo "Usage: $0 <REPO_URL> [--check-only] [--dest-dir <DIR>]" >&2
+  exit 1
+fi
+
+shift || true
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --check-only)
+      CHECK_ONLY=true
+      shift
+      ;;
+    --dest-dir)
+      DEST_DIR="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+normalize_git_url() {
+  local url="$1"
+  url="${url%.git}"
+  url="${url%/}"
+  url=$(echo "$url" | sed -E 's/^(https?:\/\/|ssh:\/\/git@|ssh:\/\/|git@)//')
+  url=$(echo "$url" | sed -E 's/:/\//')
+  echo "$url" | tr '[:upper:]' '[:lower:]'
+}
+
+TARGET_NORM=$(normalize_git_url "$REPO_URL")
+REPO_NAME=$(basename "$TARGET_NORM")
+CURRENT_DIR="$(pwd)"
+
+# Check if a specific directory matches the target URL by inspecting its remotes
+matches_target_url() {
+  local dir="$1"
+  if [ ! -d "$dir/.git" ]; then
+    return 1
+  fi
+
+  # Check all configured remotes (origin, upstream, etc.)
+  local remotes
+  remotes=$(git -C "$dir" config --get-regexp '^remote\..*\.url' 2>/dev/null | awk '{print $2}' || true)
+  for r in $remotes; do
+    local r_norm
+    r_norm=$(normalize_git_url "$r")
+    if [ "$r_norm" = "$TARGET_NORM" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+FOUND_PATH=""
+
+# ------------------------------------------------------------------------------
+# Pass 1: Fast Probe of Standard Conventions
+# ------------------------------------------------------------------------------
+FAST_CANDIDATES=(
+  "${DEST_DIR:-}"
+  "$HOME/projects/$REPO_NAME"
+  "$(dirname "$CURRENT_DIR")/$REPO_NAME"
+  "$CURRENT_DIR/$REPO_NAME"
+  "$CURRENT_DIR"
+)
+
+for cand in "${FAST_CANDIDATES[@]}"; do
+  [ -z "$cand" ] && continue
+  if matches_target_url "$cand"; then
+    FOUND_PATH="$(cd "$cand" && pwd)"
+    break
+  fi
+done
+
+# ------------------------------------------------------------------------------
+# Pass 2: Deep Scan Across Sibling & Project Roots (Handles ANY folder name!)
+# ------------------------------------------------------------------------------
+if [ -z "$FOUND_PATH" ]; then
+  SEARCH_ROOTS=()
+  PARENT_DIR="$(dirname "$CURRENT_DIR")"
+  SEARCH_ROOTS+=("$PARENT_DIR")
+  [ -d "$HOME/projects" ] && [ "$HOME/projects" != "$PARENT_DIR" ] && SEARCH_ROOTS+=("$HOME/projects")
+  [ -d "$HOME/workspace" ] && SEARCH_ROOTS+=("$HOME/workspace")
+  [ -d "$HOME/dev" ] && SEARCH_ROOTS+=("$HOME/dev")
+  [ -d "$HOME/code" ] && SEARCH_ROOTS+=("$HOME/code")
+
+  for root in "${SEARCH_ROOTS[@]}"; do
+    [ ! -d "$root" ] && continue
+    # Search maxdepth 2 for any .git directory
+    while IFS= read -r gitdir; do
+      repo_candidate="$(dirname "$gitdir")"
+      if matches_target_url "$repo_candidate"; then
+        FOUND_PATH="$(cd "$repo_candidate" && pwd)"
+        break 2
+      fi
+    done < <(find "$root" -maxdepth 2 -name ".git" -type d 2>/dev/null || true)
+  done
+fi
+
+# ------------------------------------------------------------------------------
+# Output Resolution
+# ------------------------------------------------------------------------------
+if [ -n "$FOUND_PATH" ]; then
+  BRANCH=$(git -C "$FOUND_PATH" branch --show-current 2>/dev/null || true)
+  if [ -z "$BRANCH" ]; then
+    BRANCH=$(git -C "$FOUND_PATH" rev-parse --short HEAD 2>/dev/null || echo "unknown")
+  fi
+  PORCELAIN=$(git -C "$FOUND_PATH" status --porcelain 2>/dev/null || true)
+  IS_CLEAN="true"
+  if [ -n "$PORCELAIN" ]; then
+    IS_CLEAN="false"
+  fi
+  FOLDER_NAME=$(basename "$FOUND_PATH")
+
+  echo "STATUS=ALREADY_CLONED"
+  echo "LOCAL_PATH=$FOUND_PATH"
+  echo "LOCAL_FOLDER_NAME=$FOLDER_NAME"
+  echo "CANONICAL_SLUG=$TARGET_NORM"
+  echo "CURRENT_BRANCH=$BRANCH"
+  echo "IS_CLEAN=$IS_CLEAN"
+  exit 0
+fi
+
+if [ "$CHECK_ONLY" = true ]; then
+  echo "STATUS=NOT_CLONED"
+  echo "LOCAL_PATH="
+  echo "LOCAL_FOLDER_NAME="
+  echo "CANONICAL_SLUG=$TARGET_NORM"
+  exit 1
+fi
+
+# ------------------------------------------------------------------------------
+# Fallback: Fresh Clone
+# ------------------------------------------------------------------------------
+if [ -z "$DEST_DIR" ]; then
+  if [ -d "$HOME/projects" ]; then
+    DEST_DIR="$HOME/projects/$REPO_NAME"
+  else
+    DEST_DIR="$(dirname "$CURRENT_DIR")/$REPO_NAME"
+  fi
+fi
+
+echo "📥 Repository '$REPO_URL' not found locally under any folder name. Cloning into '$DEST_DIR'..." >&2
+mkdir -p "$(dirname "$DEST_DIR")"
+git clone "$REPO_URL" "$DEST_DIR" >&2
+
+FINAL_PATH="$(cd "$DEST_DIR" && pwd)"
+BRANCH=$(git -C "$FINAL_PATH" branch --show-current 2>/dev/null || true)
+if [ -z "$BRANCH" ]; then
+  BRANCH=$(git -C "$FINAL_PATH" rev-parse --short HEAD 2>/dev/null || echo "unknown")
+fi
+
+echo "STATUS=CLONED_FRESH"
+echo "LOCAL_PATH=$FINAL_PATH"
+echo "LOCAL_FOLDER_NAME=$(basename "$FINAL_PATH")"
+echo "CANONICAL_SLUG=$TARGET_NORM"
+echo "CURRENT_BRANCH=$BRANCH"
+echo "IS_CLEAN=true"
+exit 0

package/.agents/skills/product-analyst/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: product-analyst
+description: Use when analyzing product requirements, aligning features with OKRs and Product Goals, prioritizing backlogs with Kano/MoSCoW/RICE, decomposing epics into INVEST user stories and SMART tasks, authoring Gherkin Given-When-Then acceptance criteria, or mapping domain models and failure edge cases. Do not use for writing application code, debugging implementation bugs, or running tests.
+---
+
+# Product Analyst & Requirements Architect Skill
+
+> **Core Purpose:** Bridge strategic business intent and engineering execution by grounding feature requirements in OKRs, maximizing product value via empirical backlog ordering (Kano, MoSCoW, RICE), and decomposing scope into vertically sliced INVEST user stories with Gherkin acceptance criteria and SMART developer tasks.
+
+---
+
+## 1. When to Use This Skill
+- Decomposing a broad business request, feature idea, or PRD into actionable vertical slices.
+- Evaluating alignment with strategic **Objectives & Key Results (OKRs)** and the overarching **Product Goal**.
+- Ordering and prioritizing Product Backlog items using **Kano**, **MoSCoW**, **RICE**, or **Buy a Feature**.
+- Distinguishing user-facing stories from non-story requirements (system invariants, NFRs, architectural spikes).
+- Formulating Gherkin acceptance tests before kicking off Outside-In TDD.
+- Decomposing INVEST stories into actionable, time-boxed **SMART developer tasks**.
+- Establishing Ubiquitous Language definitions for new domain models.
+
+---
+
+## 2. Step-by-Step Analysis Workflow
+
+```
+1. OKR & Goal Alignment ──► 2. Backlog Triage & Ordering ──► 3. Story vs. NFR Classification ──► 4. INVEST Stories & Gherkin ──► 5. SMART Tasks & Edge Cases
+```
+
+### Step 1: Align with OKRs & the Product Goal
+- **Product Goal Validation:** Verify how this feature advances the long-term Product Goal.
+- **OKR Mapping:** Map the feature to a specific **Objective** (qualitative "what") and its associated **Key Results** (quantitative "how").
+- **Satisfaction Gap Check:** Identify which customer pain point or satisfaction gap is addressed:
+  $$\text{Satisfaction Gap} = \text{Desired Customer Experience} - \text{Current Customer Experience}$$
+- **Deciding What NOT to Do:** Explicitly identify and eliminate speculative, low-impact sub-features.
+
+### Step 2: Prioritize via Backlog Ordering Models
+Consult [`references/backlog_ordering_techniques.md`](./references/backlog_ordering_techniques.md) to apply the optimal prioritization model:
+- **Kano Model:** Classify as *Must-be* (table stakes), *Performance* (linear satisfaction), or *Attractive* (delighter). Reject *Indifferent* or *Reverse* items.
+- **MoSCoW:** Categorize into *Must*, *Should*, *Could*, or *Won't have this time*.
+- **RICE Scoring:** Compute $(Reach \times Impact \times Confidence) / Effort$ to break ranking ties objectively.
+
+### Step 3: Classify User Stories vs. Non-Story Requirements
+Recognize that **user stories are not requirements**, but a technique to express them:
+- **User Story (3 C's: Card, Conversation, Confirmation):** Fits user-facing features where customer/business perspective is translated into software behavior via a "pidgin language".
+- **Non-Story Requirements:** If the requirement represents a system invariant, data integrity rule, security policy (OWASP), latency SLA, or an architectural spike, model it directly as a technical specification, architectural fitness test, or spike task rather than forcing an artificial `"As a user..."` persona.
+
+### Step 4: Author User Stories (INVEST Framework & Vertical Cake Slicing)
+Ensure every user story conforms to Bill Wake's **INVEST** criteria:
+- **Independent:** Sliced vertically through all layers (UI ➔ API ➔ Domain ➔ DB) without circular dependencies.
+- **Negotiable:** Captures essence and value, leaving implementation details open for pairing co-creation.
+- **Valuable:** Delivers observable benefit to the customer or business stakeholder.
+- **Estimable:** Right-sized and bounded. Spikes used for major unknowns.
+- **Small:** Sized to be completable in 1–2 development days.
+- **Testable:** Accompanied by executable, unambiguous Gherkin acceptance criteria.
+
+**The Multi-Layer Cake Rule:** Never slice horizontally (e.g. "Create database schema only"). Always slice vertically through the full stack so that every story delivers working software.
+
+### Step 5: Decompose Stories into SMART Developer Tasks
+For engineering execution, translate INVEST user stories into Bill Wake's **SMART** developer tasks:
+- **S - Specific:** Unambiguous scope without conceptual overlap.
+- **M - Measurable:** Clear pass/fail criteria (tests pass, clean code, DoD met).
+- **A - Achievable:** Realistically executable; triggers early help request if blocked.
+- **R - Relevant:** Justified by direct contribution to parent story.
+- **T - Time-boxed:** Limited to 2–4 hours (never exceeding 1 day).
+
+### Step 6: Construct the Edge Case & Failure Matrix
+Map all failure paths to HTTP status codes (`400`, `401`, `403`, `404`, `409`, `422`, `429`, `500`) and RFC 7807 problem details.
+
+---
+
+## 3. Gotchas & What NOT to Do
+
+- **DO NOT** confuse output (features shipped, story points burned) with outcome (value delivered, satisfaction gap closed).
+- **DO NOT** write horizontal, technical user stories (e.g., *"As a developer, I want a database table"*).
+- **DO NOT** force technical constraints, security policies, or infrastructure upgrades into user story syntax. Treat them as non-story requirements or architectural spikes.
+- **DO NOT** omit the Out-of-Scope ("Won't Have this time") section. Lack of negative boundaries causes runaway scope bloat.
+- **DO NOT** allow developer tasks to be open-ended without a measurable time-box. If a task exceeds 4 hours, it must be split or paired.
+- **DO NOT** skip failure paths in Gherkin scenarios. Happy-path-only requirements lead to production defects.
+
+---
+
+## 4. Structured Output Template
+
+```markdown
+# Product Specification: [Feature Name]
+
+## 1. Strategic Alignment & Product Goal
+- **Product Goal:** [Target milestone / commitment]
+- **Target OKR:**
+  - **Objective:** [Qualitative, inspiring What]
+  - **Key Result(s):** [Quantitative, measurable outcome How]
+- **Target Satisfaction Gap:** [Customer pain point addressed]
+- **Prioritization Category:** [Kano: Must-be / Performance / Attractive | MoSCoW: Must / Should | RICE Score: X]
+
+## 2. In-Scope vs. Out-of-Scope (Non-Goals)
+- **In-Scope (Must/Should):** ...
+- **Out-of-Scope (Won't Have This Time):** ...
+
+## 3. Ubiquitous Language & Entity Relationships
+- **[Term 1]**: [Definition grounded in domain invariants]
+- **[Term 2]**: [Definition grounded in domain invariants]
+
+## 4. User Stories & Gherkin Acceptance Scenarios
+
+### US-01: [User Story Title]
+**As a** [role]  
+**I want to** [action]  
+**So that** [value]
+
+```gherkin
+Scenario: [Happy path]
+  Given ...
+  When ...
+  Then ...
+
+Scenario: [Edge case / Failure path]
+  Given ...
+  When ...
+  Then ...
+```
+
+## 5. SMART Developer Tasks (Inner-Loop Breakdown)
+- [ ] **Task 1 [Specific & Time-boxed: 2h]:** [Technical description, e.g. Domain entity and value object invariants with unit test RED-GREEN]
+- [ ] **Task 2 [Specific & Time-boxed: 3h]:** [Use case & secondary repository implementation with integration tests]
+- [ ] **Task 3 [Specific & Time-boxed: 2h]:** [HTTP controller endpoint & RFC 7807 error handling]
+- [ ] **Task 4 [Specific & Time-boxed: 3h]:** [UI view integration, TanStack query hooks, accessible Radix primitives]
+
+## 6. Edge Case & Error Response Matrix
+| Condition | HTTP Status | Error Code | Expected Behavior |
+|---|---|---|---|
+| Invalid payload | 400 | `VALIDATION_ERROR` | Return field errors |
+| Cross-tenant attempt | 403 / 404 | `FORBIDDEN` | Mask existence or block |
+| Duplicate invariant | 409 | `CONFLICT` | Prevent double-submission |
+```
+
+---
+
+## 5. Subdirectories & Progressive Resources
+- [references/invest_checklist.md](./references/invest_checklist.md): Checklist for evaluating user stories against Bill Wake's INVEST criteria and cake-slicing rules.
+- [references/smart_tasks.md](./references/smart_tasks.md): Guide and patterns for breaking stories into SMART developer tasks.
+- [references/backlog_ordering_techniques.md](./references/backlog_ordering_techniques.md): Matrix and decision trees for Kano, MoSCoW, RICE, and Buy a Feature.
+- [references/okr_alignment_guide.md](./references/okr_alignment_guide.md): Framework for authoring Objectives, Key Results, and connecting them to Product Goals.
+- [references/gherkin_patterns.md](./references/gherkin_patterns.md): Reusable Gherkin scenario patterns for REST APIs and UI interactions.