@pasajero_0/agent-stack 0.1.0

package/templates/claude/hooks/guard-bash.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# PreToolUse(Bash) guard — enforces hard prohibitions.
+set -euo pipefail
+
+cmd=$(jq -r '.tool_input.command // empty')
+[ -z "$cmd" ] && exit 0
+
+if printf '%s' "$cmd" | grep -Eq '(^|[&|;]|&&)[[:space:]]*git[[:space:]]+push\b'; then
+  echo "Blocked: 'git push' is manual-only — the team pushes by hand." >&2
+  exit 2
+fi
+
+# Package-manager guard. This repo is {{PM}}-only.
+if printf '%s' "$cmd" | grep -Eq '(^|[&|;]|&&)[[:space:]]*({{FORBIDDEN_PM}})[[:space:]]'; then
+  echo "Blocked: this repo uses {{PM}} only." >&2
+  exit 2
+fi
+
+exit 0

package/templates/claude/hooks/guard-file.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# PreToolUse(Edit|Write|MultiEdit) guard — protects generated + secret files.
+set -euo pipefail
+
+path=$(jq -r '.tool_input.file_path // empty')
+[ -z "$path" ] && exit 0
+
+# Auto-generated build outputs — never hand-edit.
+case "$path" in
+  {{GEN_GLOBS}})
+    echo "Blocked: this file is auto-generated (build output) — never edit it by hand." >&2
+    exit 2
+    ;;
+esac
+
+# Lockfile — regenerate via the package manager, never hand-edit.
+case "$path" in
+  *{{LOCKFILE}})
+    echo "Blocked: {{LOCKFILE}} is generated by {{PM}} — never edit it by hand." >&2
+    exit 2
+    ;;
+esac
+
+case "$path" in
+  *.env|*.env.*)
+    jq -n '{
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "ask",
+        permissionDecisionReason: "Editing an env file — it may contain secrets. Confirm before writing."
+      }
+    }'
+    exit 0
+    ;;
+esac
+
+exit 0

package/templates/claude/hooks/post-edit-lint.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# PostToolUse(Edit|Write|MultiEdit) — lint edited source files, surface issues as additionalContext.
+# Does NOT modify the file (no --fix) — keeps Claude's file-state tracking consistent.
+# NOTE: this repo currently has no linter installed, so this hook self-disables
+# (the `[ -x "$LINTER" ] || exit 0` guard). Install a linter or point LINTER at it to enable.
+set -euo pipefail
+
+input=$(cat)
+path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
+[ -z "$path" ] && exit 0
+
+case "$path" in
+  *.ts|*.tsx|*.js|*.jsx|*.mts|*.cts) ;;
+  *) exit 0 ;;
+esac
+
+case "$path" in
+  *.gen.*|*/node_modules/*|*/dist/*|*/build/*|*/storybook-static/*|*/coverage/*) exit 0 ;;
+esac
+
+LINTER="${CLAUDE_PROJECT_DIR:-$(pwd)}/node_modules/.bin/eslint"
+[ -x "$LINTER" ] || LINTER="$(command -v eslint || true)"
+[ -x "$LINTER" ] || exit 0
+
+CACHE_DIR=/tmp/claude-eslint-cache
+mkdir -p "$CACHE_DIR"
+
+output=$(timeout 20 "$LINTER" \
+  --cache \
+  --cache-location "$CACHE_DIR/" \
+  --cache-strategy content \
+  --format=json \
+  --no-warn-ignored \
+  "$path" 2>/dev/null) || true
+
+# Parse only if output is valid JSON (eslint may bail on config errors)
+echo "$output" | jq empty 2>/dev/null || exit 0
+
+filtered=$(echo "$output" | jq -r '
+  .[].messages[]?
+  | select(.severity >= 1)
+  | "  \(if .severity==2 then "✘" else "⚠" end) line \(.line):\(.column)  \(.message)  (\(.ruleId // "—"))"
+' 2>/dev/null)
+
+if [ -n "$filtered" ]; then
+  jq -nc --arg ctx "Linter issues in $(basename "$path"):
+$filtered" '{
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: $ctx
+    }
+  }'
+fi
+
+exit 0

package/templates/claude/hooks/post-edit-verify.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# PostToolUse(Edit|Write|MultiEdit) — D12 post-apply verify.
+# Active ONLY when at least one migration plan exists in .claude/tmp/.
+# Outside active migrations: zero noise, near-zero latency.
+#
+# Caveat: diff is git working-tree vs HEAD, so it shows ALL uncommitted
+# changes to the file, not only the change from the just-completed tool call.
+# That caveat is surfaced in the additionalContext so Claude does not
+# over-interpret unrelated edits.
+#
+# `set -e` and `pipefail` deliberately omitted: `git diff | head -200`
+# triggers SIGPIPE on diffs >200 lines, which would crash the hook under
+# pipefail. Defensive philosophy: always exit 0.
+#
+# JSON build: python3 (stdin + UTF-8 "replace" decode) preferred — survives
+# non-UTF-8 bytes from arbitrary diff content. Fallback: `jq --rawfile` via
+# temp file if python3 is absent.
+#
+# Historical note: do NOT use `echo "$out" | jq .` to post-process — the hook
+# runner may exec `zsh -c`, and zsh's `echo` interprets `\n` escapes, turning
+# valid escaped JSON back into raw LF before parsing. Use `printf '%s'`.
+set -u
+
+# (1) Early-exit if no active migration plan.
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PLAN_DIR="$PROJECT_DIR/.claude/tmp"
+ls "$PLAN_DIR"/*-plan.md >/dev/null 2>&1 || exit 0
+
+# (2) Parse file path from tool_input.
+input=$(cat)
+path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
+[ -z "$path" ] && exit 0
+
+# (3) Normalize to absolute path so case-glob matches reliably for relative paths.
+case "$path" in
+  /*) abs_path="$path" ;;
+  *)  abs_path="$PROJECT_DIR/$path" ;;
+esac
+
+# (4) Skip noise paths (same filter spirit as post-edit-lint.sh).
+case "$abs_path" in
+  *.gen.*|*/node_modules/*|*/dist/*|*/build/*|*/storybook-static/*|*/coverage/*) exit 0 ;;
+esac
+
+# (5) Build diff: tracked → git diff -U2 (truncated 200 lines); untracked → head -50.
+cd "$PROJECT_DIR" 2>/dev/null || exit 0
+if git ls-files --error-unmatch -- "$abs_path" >/dev/null 2>&1; then
+  diff_output=$(timeout 10 git diff -U2 -- "$abs_path" 2>/dev/null | head -200)
+else
+  diff_output=$(head -50 "$abs_path" 2>/dev/null)
+fi
+[ -z "$diff_output" ] && exit 0
+
+# (6) Build ctx then emit JSON.
+ctx="POST-APPLY VERIFY (D12) $abs_path:
+$diff_output
+
+(diff may include earlier uncommitted changes to this file)
+
+Compare against the approved preview table. Report any mismatch before marking the step done."
+
+if command -v python3 >/dev/null 2>&1; then
+  printf '%s' "$ctx" | python3 -c 'import json,sys; print(json.dumps({"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":sys.stdin.buffer.read().decode("utf-8","replace")}}))'
+else
+  tmpf=$(mktemp)
+  printf '%s' "$ctx" > "$tmpf"
+  jq -nc --rawfile ctx "$tmpf" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$ctx}}'
+  rm -f "$tmpf"
+fi
+
+exit 0

package/templates/claude/hooks/session-start-context.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# SessionStart — write start-marker for Stop hook + inject git context (only on fresh starts).
+set -euo pipefail
+
+input=$(cat)
+session_id=$(echo "$input" | jq -r '.session_id // "unknown"')
+cwd=$(echo "$input" | jq -r '.cwd // "."')
+src=$(echo "$input" | jq -r '.source // "startup"')
+
+mkdir -p /tmp/claude-sessions
+# Sweep stale markers (>24h) so /tmp doesn't grow forever
+find /tmp/claude-sessions -maxdepth 1 -type f -name '*.start' -mtime +1 -delete 2>/dev/null || true
+
+# Always write a fresh marker for this session — Stop hook compares memory mtimes against it
+touch "/tmp/claude-sessions/$session_id.start"
+
+# Heavy git context: only on a truly new context window
+case "$src" in
+  startup|clear)
+    if git -C "$cwd" rev-parse 2>/dev/null >/dev/null; then
+      branch=$(git -C "$cwd" rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)
+      last=$(git -C "$cwd" log -1 --pretty='%h %s' 2>/dev/null || echo none)
+      changed=$(git -C "$cwd" status --short 2>/dev/null | head -20)
+      echo "## Session context"
+      echo
+      echo "- Branch: \`$branch\`"
+      echo "- Last commit: $last"
+      if [ -n "$changed" ]; then
+        echo "- Working tree (first 20 entries):"
+        echo '```'
+        echo "$changed"
+        echo '```'
+      else
+        echo "- Working tree: clean"
+      fi
+      echo
+    fi
+    ;;
+esac
+
+# Active migration plan(s) — fire on every source. Cheap (3 lines); most valuable
+# on `compact` where prior nuances were summarized away.
+if ls "${CLAUDE_PROJECT_DIR:-$cwd}"/.claude/tmp/*-plan.md >/dev/null 2>&1; then
+  echo "⚠️ Active migration plan(s):"
+  ls "${CLAUDE_PROJECT_DIR:-$cwd}"/.claude/tmp/*-plan.md
+  echo "Re-read before acting; use /migration to continue."
+  echo
+fi
+
+# Pending /reflect notice — always (cheap), regardless of source
+if [ -f /tmp/.claude-reflect-pending ]; then
+  echo "💡 Memory was modified in the previous session — consider running \`/reflect\` to consolidate."
+  echo
+  rm -f /tmp/.claude-reflect-pending
+fi
+
+exit 0

package/templates/claude/hooks/stop-flag-reflect.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Stop — fires every assistant turn. Keep work tiny.
+# If any memory file changed since session start, raise the /reflect-pending flag.
+set -euo pipefail
+
+input=$(cat)
+session_id=$(echo "$input" | jq -r '.session_id // "unknown"')
+marker="/tmp/claude-sessions/$session_id.start"
+[ -f "$marker" ] || exit 0
+
+# Self-derive the auto-memory dir slug from the session cwd (every "/" → "-").
+cwd=$(echo "$input" | jq -r '.cwd // empty')
+[ -z "$cwd" ] && exit 0
+slug="${cwd//\//-}"
+MEM="$HOME/.claude/projects/${slug}/memory"
+[ -d "$MEM" ] || exit 0
+
+# -quit stops at first match → ~few ms even if memory has many files
+if find "$MEM" -maxdepth 1 -name '*.md' -newer "$marker" -print -quit 2>/dev/null | grep -q .; then
+  touch /tmp/.claude-reflect-pending
+fi
+
+# Do NOT remove the marker — Stop fires on every turn within the same session.
+exit 0

package/templates/claude/rules/README.md

@@ -0,0 +1,33 @@
+# Path-scoped rules
+
+This directory holds **path-scoped rules** — narrow, machine-checkable conventions that activate
+only when a matching file is touched (frontmatter `paths:` glob).
+
+**Rules are NOT shipped or copied — they are generated per-repo.** `agent-stack` deliberately leaves
+this directory empty at deploy time, because rules must reflect *this* codebase's real conventions,
+not another project's.
+
+To generate them: open `claude` in this repo and run the **pattern-scout** subagent against your
+code and architecture docs. It drafts rules marked `[DRAFT]`; review them, keep what fits, delete
+the rest.
+
+Each rule file looks like:
+
+```markdown
+---
+description: <one line — what this rule enforces and when it fires>
+paths:
+  - "<glob, e.g. src/**/*.ts>"
+---
+
+# <Rule name>
+
+## Do
+- <convention> — detect: `<grep regex>` — severity: critical/warning/suggestion
+
+## Don't
+- <banned pattern> — detect: `<grep regex>` — severity: ...
+
+## Why
+<the failure mode this rule prevents>
+```

package/templates/claude/skills/ci-testing-patterns.md

@@ -0,0 +1,22 @@
+# CI / Testing Patterns
+
+Validated knowledge from this project's test + CI setup. Replace with **your project's** runner and
+CI provider as you learn them.
+
+## Test runner
+
+- Config: `<test config file>`; run focused with `<runner> <substring>`.
+- Test the logic-heavy modules; mock external processes/IO, not internal modules.
+
+## CI
+
+A minimal pipeline on PR:
+- install dependencies (frozen lockfile)
+- typecheck
+- test
+- lint commit messages (if the repo enforces a commit convention)
+
+## Gotchas
+
+Keep a running list of tool issues that bit CI (version quirks, cache keys, runtime drift), one
+line each, so the next debugging session starts from known causes.

package/templates/claude/skills/migration/SKILL.md

@@ -0,0 +1,35 @@
+---
+description: Drive a multi-step migration or refactor against a plan file in `.claude/tmp/<task>-plan.md`. Loads the active plan into context, walks the next pending step under the plan's invariants, marks completed steps. Trigger when the user says "start migration", "continue migration", "next migration step", or similar.
+disable-model-invocation: false
+---
+
+## Active plan(s)
+
+<!-- Path resolution: `${CLAUDE_SKILL_DIR%/skills/*}/tmp` strips `/skills/<name>` from this skill's directory to get `<repo>/.claude/`, then appends `/tmp`. Requires this SKILL.md to live at `<repo>/.claude/skills/migration/SKILL.md` — moving the directory breaks the resolver. -->
+
+!`d="${CLAUDE_SKILL_DIR%/skills/*}/tmp"; if ls "$d"/*-plan.md >/dev/null 2>&1; then for f in "$d"/*-plan.md; do printf '\n=== %s ===\n' "$f"; cat "$f"; done; else echo "(no active plan in $d — create one first)"; fi`
+
+## How to drive a migration
+
+1. **If no plan is loaded above** — draft one from the decisions in the current conversation.
+   Capture every committed invariant (numbered `Dn` style: scope, format, deviation policy,
+   completion gate), plus a top-level `## Open questions` section recording every unresolved
+   question raised by the user; it stays open until that question is explicitly closed. Save to
+   `.claude/tmp/<task>-plan.md`, show it to the user, and wait for explicit approval. Re-read the
+   saved plan from disk before proposing the first step.
+
+2. **If a plan is loaded above** — identify the next pending step from the checklist at the bottom
+   of the plan. Re-read the affected source files (do NOT cite from memory). Open the diff preview
+   with a compliance header that names which invariants are honoured — for example:
+   `Plan check: D1, D4 — ok; D3 — n/a`. Each invariant touched must be either honoured or flagged
+   as a **deviation** (`ОТКЛОНЕНИЕ ОТ ПЛАНА`) with rationale, awaiting explicit approval before the
+   diff appears.
+
+3. **After applying a step** — verify the actual diff against the approved preview (call this the
+   D12 verify: run `git diff` or re-read the changed lines; a divergence in either direction must
+   be surfaced and explicitly accepted before the step is marked done). Then mark its checklist
+   entry as `[x]` in the plan file with a one-line note about what landed. Run any gate the plan
+   specifies (e.g. a `grep` clean of old paths) before declaring the step done.
+
+4. **When every step is checked off** — propose deleting the plan file, after confirming with the
+   user that the migration is fully landed and verified.

package/templates/claude/skills/mr-description/SKILL.md

@@ -0,0 +1,56 @@
+---
+description: Draft a GitHub pull request description for the current branch following a compact template (what / scenarios / verification). Use when the user asks to write, draft, or generate a PR description for the current branch.
+allowed-tools: Bash(git rev-parse:*), Bash(git log:*), Bash(git diff:*)
+---
+
+## Current branch state
+
+- Branch: !`git rev-parse --abbrev-ref HEAD`
+- Commits ahead of {{MAIN_BRANCH}} (origin first, local fallback):
+
+!`git log origin/{{MAIN_BRANCH}}..HEAD --oneline 2>/dev/null | head -30 || git log {{MAIN_BRANCH}}..HEAD --oneline 2>/dev/null | head -30 || echo "(no upstream or local {{MAIN_BRANCH}} branch found)"`
+
+- Files changed (top 20):
+
+!`git diff origin/{{MAIN_BRANCH}}...HEAD --stat --stat-count=20 2>/dev/null || git diff {{MAIN_BRANCH}}...HEAD --stat --stat-count=20 2>/dev/null || echo "(diff unavailable)"`
+
+## Style rules
+
+- "What" block ≤ 2 sentences. State user-visible behaviour / CLI surface change; no implementation
+  detail. If you need more than 2 sentences, the scope is too wide — split.
+- "Scenarios" use imperative + arrow notation: `<command> → <expected>`. Not full sentences.
+- For a CLI, scenarios are commands the reviewer runs (e.g. `agent-stack detect → lists Claude
+  Code`); state which directory / fixture to run them in if it matters.
+- Link the GitHub issue narratively or with `Closes #NN` — this repo has no Jira.
+
+## Delivery format
+
+Wrap the entire PR body in a **single fenced code block** (use four backticks if the body itself
+contains code fences). The user copies the block once; GitHub renders markdown on paste. Do NOT
+render markdown inline in the reply — bold/lists/headers won't survive the clipboard hop.
+
+## Template
+
+````markdown
+**What this PR does / why we need it:**
+
+<One- or two-sentence summary of the user-visible / CLI behaviour change.>
+
+**Scenarios**
+
+1. **<Scenario name>** — `<command>` → <expected outcome>.
+2. **<Scenario name>** — `<command>` → <expected outcome>.
+
+**Verification**
+
+- `{{PM}} typecheck && {{PM}} test` — green.
+
+Closes #<issue>
+````
+
+## When to deviate
+
+- **Bug-fix PR:** add a "**Reproduction**" line above "Scenarios" with exact repro steps, then
+  scenarios verify the fix.
+- **Pure refactor / chore:** drop "Scenarios"; replace with "No behaviour change — verified by
+  `{{PM}} test`".

package/templates/claude/skills/repo-structure.md

@@ -0,0 +1,22 @@
+# Repository Structure
+
+Template for documenting this repo's layout so agents can locate code and respect boundaries. Fill
+the tables with **this project's** actual structure.
+
+## Layout
+
+| Path     | Purpose          |
+| -------- | ---------------- |
+| `<path>` | <what lives here> |
+
+## Tooling
+
+- **Package manager**: {{PM}} only.
+- **Build**: `<build command>` → `<output dir>`.
+- **Typecheck / static gate**: `<typecheck command>`.
+- **Test**: `<test command>`.
+
+## Where new files go
+
+- New <unit> → `<path>` (+ register in `<entry>`).
+- New test → mirror the source path under the test dir.

package/templates/claude/skills/team-conventions.md

@@ -0,0 +1,31 @@
+# Team Conventions
+
+Fill each section with **this project's** actual rules. The structure below is the transferable
+part; the values are placeholders the deploying agent (or you) should replace.
+
+## Commits
+
+Format: `type(scope): message` (Conventional Commits if the repo runs commitlint).
+
+**Types**: feat, fix, chore, refactor, test, docs, style, perf, ci, build, revert
+**Scopes**: enumerate the areas the project uses as scopes.
+**Issue reference**: how this repo links work (e.g. `Closes #NN`).
+
+## Branches
+
+Main branch: `{{MAIN_BRANCH}}`. `git push` is manual-only (the guard-bash hook blocks the agent).
+
+## Git hooks
+
+- `pre-commit`: <linter/typecheck on staged files, or empty>.
+- `commit-msg`: <commit-message linting, if any>.
+
+## Code style
+
+Capture the load-bearing rules: typing strictness, import conventions, formatter settings, naming.
+
+## Hard prohibitions
+
+- **{{PM}} only** — other package managers are blocked by the guard-bash hook.
+- **Never `git push`** from the agent — manual-only.
+- **Never hand-edit generated files** ({{GEN_GLOBS}}, {{LOCKFILE}}).