@evertonferreira96/agents 0.0.0-stage → 0.1.1

package/.claude/hooks/orchestrator-guard.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# PreToolUse Edit|Write|MultiEdit|NotebookEdit: the main session (no agent_id) writes only docs/plans, docs/adr, docs/README.md, .claude/ and root *.md.
+input=$(cat)
+
+field() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$input" | jq -r "$1 // empty"
+  else
+    printf '%s' "$input" | sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"\(\([^\"\\\\]\|\\\\.\)*\)\".*/\1/p" | head -n1
+  fi
+}
+
+deny() {
+  echo "Orchestrator never edits code. Dispatch /quick or an implementer. ($1)" >&2
+  exit 2
+}
+
+[ -n "$(field '.agent_id' agent_id)" ] && exit 0
+
+path=$(field '.tool_input.file_path // .tool_input.notebook_path' file_path)
+[ -z "$path" ] && path=$(field '.tool_input.notebook_path' notebook_path)
+command -v jq >/dev/null 2>&1 || path=$(printf '%b' "$path")
+[ -z "$path" ] && exit 0
+
+case "$path" in
+  */../*|../*|*/..) deny "$path" ;;
+esac
+
+root=${CLAUDE_PROJECT_DIR:-$(field '.cwd' cwd)}
+rel=$path
+case "$rel" in
+  */.claude/worktrees/*/*) rel=$(printf '%s' "$rel" | sed -E 's#^.*/\.claude/worktrees/[^/]+/##') ;;
+  .claude/worktrees/*/*) rel=$(printf '%s' "$rel" | sed -E 's#^\.claude/worktrees/[^/]+/##') ;;
+  "$root"/*) rel=${rel#"$root"/} ;;
+  /*)
+    case "$rel" in
+      */.claude/*) exit 0 ;;
+      *) deny "$path" ;;
+    esac
+    ;;
+esac
+rel=${rel#./}
+
+case "$rel" in
+  docs/plans/*|docs/adr/*|docs/README.md|.claude/*) exit 0 ;;
+  */*) deny "$rel" ;;
+  *.md) exit 0 ;;
+  *) deny "$rel" ;;
+esac

package/.claude/hooks/post-compact.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# PostCompact / SessionStart(compact): re-inject the newest active plan after context compaction.
+input=$(cat)
+
+if command -v jq >/dev/null 2>&1; then
+  cwd=$(printf '%s' "$input" | jq -r '.cwd // empty')
+else
+  cwd=$(printf '%s' "$input" | sed -n 's/.*"cwd"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
+fi
+cwd=${cwd:-$PWD}
+
+dir="$cwd/docs/plans"
+[ -d "$dir" ] || exit 0
+
+plan=""
+while IFS= read -r f; do
+  case "$f" in */README.md) continue ;; esac
+  grep -Eiq '^status: *done' "$f" && continue
+  plan=$f
+  break
+done < <(ls -t "$dir"/*.md 2>/dev/null)
+[ -n "$plan" ] || exit 0
+
+printf 'Re-injected after compaction. Active plan: %s\n' "${plan#$cwd/}"
+head -n 120 "$plan"
+exit 0

package/.claude/hooks/readonly-guard.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# PreToolUse for readonly agents: edits only in .claude/agent-memory/, Bash only from an allowlist.
+input=$(cat)
+
+field() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$input" | jq -r "$1 // empty"
+  else
+    printf '%s' "$input" | sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"\(\([^\"\\\\]\|\\\\.\)*\)\".*/\1/p" | head -n1
+  fi
+}
+
+deny() {
+  echo "Readonly agent: $1" >&2
+  exit 2
+}
+
+tool=$(field '.tool_name' tool_name)
+
+case "$tool" in
+  Write|Edit|MultiEdit|NotebookEdit)
+    path=$(field '.tool_input.file_path // .tool_input.notebook_path' file_path)
+    command -v jq >/dev/null 2>&1 || path=$(printf '%b' "$path")
+    case "$path" in
+      */../*|../*) deny "edits allowed only in .claude/agent-memory/" ;;
+      .claude/agent-memory/*|*/.claude/agent-memory/*) exit 0 ;;
+      *) deny "edits allowed only in .claude/agent-memory/" ;;
+    esac
+    ;;
+  Bash)
+    cmd=$(field '.tool_input.command' command)
+    command -v jq >/dev/null 2>&1 || cmd=$(printf '%b' "$cmd")
+    [ -z "$cmd" ] && exit 0
+    case "$cmd" in
+      *'$('*|*'`'*) deny "command not in allowlist" ;;
+    esac
+    stripped=$(printf '%s' "$cmd" | sed -E 's#[0-9]?>[[:space:]]*/dev/null##g; s#2>&1##g')
+    case "$stripped" in
+      *'>'*) deny "command not in allowlist" ;;
+    esac
+    allow='^(graphify |git (log|diff|show|status|blame|worktree list)|gh (issue|pr) view|(ls|cat|head|tail|wc|grep|rg|find|tree|pwd|cd)( |$)|python3? [^;&|]*search\.py)'
+    segments=$(printf '%s\n' "$stripped" | sed -E 's/(\&\&|\|\||;|\|)/\n/g')
+    while IFS= read -r seg; do
+      s=$(printf '%s' "$seg" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//; s/[[:space:]]+/ /g')
+      [ -z "$s" ] && continue
+      s=$(printf '%s' "$s" | sed -E 's/^git( -C [^ ]+| -c [^ ]+)+/git/')
+      printf '%s' "$s" | grep -Eq "$allow" || deny "command not in allowlist"
+      printf '%s' " $s " | grep -Eq '^ find .* -(exec|execdir|delete|ok|fprint)' && deny "command not in allowlist"
+    done <<< "$segments"
+    exit 0
+    ;;
+esac
+
+exit 0

package/.claude/hooks/stop-verify.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Stop: run lint and test before the session may finish, only when the tree has changes.
+input=$(cat)
+
+if command -v jq >/dev/null 2>&1; then
+  active=$(printf '%s' "$input" | jq -r '.stop_hook_active // false')
+  cwd=$(printf '%s' "$input" | jq -r '.cwd // empty')
+else
+  printf '%s' "$input" | grep -Eq '"stop_hook_active"[[:space:]]*:[[:space:]]*true' && active=true || active=false
+  cwd=$(printf '%s' "$input" | sed -n 's/.*"cwd"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
+fi
+
+[ "$active" = "true" ] && exit 0
+cwd=${cwd:-$PWD}
+if st=$(git -C "$cwd" status --porcelain 2>/dev/null) && [ -z "$st" ]; then
+  exit 0
+fi
+[ -f "$cwd/package.json" ] || exit 0
+
+marker="$cwd/.claude/.stop-verify-ran"
+if [ -f "$marker" ] && [ -n "$(find "$marker" -mmin -10 2>/dev/null)" ]; then
+  exit 0
+fi
+
+cd "$cwd" || exit 0
+
+if [ -f pnpm-lock.yaml ]; then pm=pnpm
+elif [ -f yarn.lock ]; then pm=yarn
+else pm=npm
+fi
+
+log=$(mktemp)
+trap 'rm -f "$log"' EXIT
+
+for script in lint test; do
+  grep -q "\"$script\"[[:space:]]*:" package.json || continue
+  if command -v timeout >/dev/null 2>&1; then
+    timeout 300 "$pm" run "$script" >"$log" 2>&1
+  else
+    "$pm" run "$script" >"$log" 2>&1
+  fi
+  rc=$?
+  if [ $rc -ne 0 ]; then
+    echo "--- $pm run $script (exit $rc), last 40 lines ---" >&2
+    tail -n 40 "$log" >&2
+    echo "Stop blocked: lint/test failed, fix before finishing" >&2
+    exit 2
+  fi
+done
+
+mkdir -p "$cwd/.claude" && touch "$marker"
+exit 0

package/.claude/rules/api.md

@@ -0,0 +1,21 @@
+---
+paths:
+  - "apps/*api*/**"
+  - "apps/*-api/**"
+  - "packages/*api*/**"
+  - "services/**"
+  - "**/nest-cli.json"
+  - "**/*.controller.ts"
+  - "**/*.surface.ts"
+  - "**/*.guard.ts"
+  - "**/*.dto.ts"
+  - "**/*.module.ts"
+  - "**/*.port.ts"
+  - "**/*.adapter.ts"
+  - "**/openapi.json"
+---
+
+# API code
+
+Load skill `arch-api` before changing code here. Server-side work is delegated to `/api`.
+New boundary, table or integration: run `/architect` first.

package/.claude/rules/db.md

@@ -0,0 +1,9 @@
+---
+paths: ["**/migrations/**", "**/migration/**", "**/db/**", "**/database/**", "**/schema/**", "**/*.sql", "**/repositories/**", "**/*.repository.ts", "**/entities/**", "**/*.entity.ts", "**/drizzle/**", "**/drizzle.config.*", "**/prisma/**", "**/schema.prisma", "**/knexfile.*", "**/ormconfig.*", "**/typeorm/**", "**/seeds/**", "**/seeders/**", "**/sgbds/**", "**/*.repository.adapter.ts", "**/*.sql.ts"]
+---
+
+# Database code
+
+Load skill `arch-db` before writing SQL, schema, migrations, indexes, seeds or repository queries (Postgres or MySQL); it points to `postgres-best-practices` for Postgres depth.
+New table, partitioning, replica or change of data ownership: run `/architect` first (storage trigger).
+Migrations must be reversible, zero-downtime (expand/contract) and run inside the repo's existing migration tool; do not invent a new one.

package/.claude/rules/delivery-diagram.md

@@ -0,0 +1,16 @@
+---
+paths: ["apps/**", "src/**", "packages/**"]
+---
+
+# Delivery diagram
+
+Required only when a delivery changes the flow between modules, services or events
+(new hop, new route/job/topic, new fallback, changed ordering). Not for changes inside one function.
+
+- Put a Mermaid `flowchart` or `sequenceDiagram` in the user-facing report.
+- Show the real code path (module, service, topic names). Do not invent hops.
+- Mark what is new or changed vs unchanged (e.g. `:::new` class or "(new)" in the label).
+- If a gate/flag exists, show both paths or a decision node.
+- If the repo has a draw.io playbook for that flow, update it in the same delivery.
+
+Skip for typo, docs, rename or internal refactor with no control-flow change, or when the user declines.

package/.claude/rules/git-workflow.md

@@ -0,0 +1,34 @@
+# Git workflow
+
+## New task
+
+- One task worktree per task, inside the repo:
+  `git fetch origin && git worktree add .claude/worktrees/<slug> -b <branch> origin/<default>`.
+  Steps in skill `orchestrate` section 2; then move the session into it (`EnterWorktree` or `claude -w <slug>`).
+  Never `git checkout` a branch in the shared cwd: parallel sessions share it.
+- Branch names, lowercase: `type/sc-<number>` with a ticket id (`feat/sc-133903`), else `type/<short-slug>`.
+  `type` is one of `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `ci`. Slug = branch with `/` -> `-`.
+- If the tree is dirty with unrelated changes, stop and ask. Do not stash or discard.
+
+## Implementer isolation (decided per spawn by the orchestrator)
+
+- Sequential or single-scope work (all M, dependent L steps): the implementer works in the task worktree.
+  Brief: `Worktree: <task-wt>`, `Commit: no`. The implementer leaves changes uncommitted; the orchestrator commits.
+- Truly parallel independent scopes (L): spawn with Agent `isolation: "worktree"`. `worktree.baseRef: head`
+  branches it from the task worktree HEAD. Brief: `Commit: yes`. The implementer commits on its own branch
+  with scoped `git add <paths>` and returns branch name and worktree path.
+- Integration: `git -C <task-wt> merge --no-ff <branch>`, or when the merge is noisy
+  `git -C <impl-wt> diff <base>...HEAD | git -C <task-wt> apply --3way`. Resolve conflicts, commit, then continue.
+
+## Commit
+
+- Stage only this task's files with explicit paths. Review `git status` and `git diff` first.
+- Never stage `.env*`, credentials or key files unless the user names the file.
+- Conventional commits. Subject says why, 1-2 sentences. Pass the message with a HEREDOC:
+  `git commit -m "$(cat <<'MSG' ... MSG)"`.
+- Never use `--no-verify`, `--amend` or `-i` unless the user asks. No empty commits.
+- Never `git add -A`, `git add .`, `git reset --hard`, `git checkout .`, `git clean -f`, `git stash`.
+
+## Push and PR
+
+Never `git push` or open/merge/edit a PR unless the user explicitly asks. The guard-bash hook enforces this.

package/.claude/rules/graphify.md

@@ -0,0 +1,3 @@
+# Graphify
+
+If `graphify-out/graph.json` exists: run `graphify query "<question>"`, `graphify path "<A>" "<B>"` or `graphify explain "<concept>"` before grep for architecture questions, then read only the cited files; read `graphify-out/GRAPH_REPORT.md` only for broad review. The graph is refreshed by the graphify-update hook after edits. If `graphify-out/graph.json` does not exist, do nothing graphify-related.

package/.claude/rules/mobile.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "apps/mobile/**"
+  - "apps/*mobile*/**"
+  - "apps/*app*/**"
+  - "apps/*rn*/**"
+  - "apps/*expo*/**"
+  - "**/app.json"
+  - "**/app.config.*"
+  - "**/eas.json"
+  - "**/metro.config.*"
+  - "**/App.tsx"
+  - "**/*.screen.tsx"
+  - "**/*.navigator.tsx"
+  - "**/src/screens/**"
+  - "**/app/_layout.tsx"
+---
+
+# Mobile code
+
+Load skill `arch-app` before changing code here. Implementation is delegated to `/app`.
+Visual or design-system work goes to `/ui`.

package/.claude/rules/tickets.md

@@ -0,0 +1,9 @@
+# Tickets
+
+Read tickets (Shortcut `SC-#####`, GitHub issues, or the workspace tracker) when needed for scope.
+
+Never create, update, assign, transition or comment on a ticket or PR (Shortcut stories, GitHub issues,
+PR comments/reviews) unless the user explicitly asks for that write.
+
+"Start the task", implement, review and commit do not count as permission. The guard-bash hook blocks
+`gh issue create|comment|edit|close`, `gh pr comment|review|create` and Shortcut CLI writes.

package/.claude/rules/ui.md

@@ -0,0 +1,14 @@
+---
+paths: ["**/components/**", "**/ui/**", "**/design-system/**", "**/*.css", "**/tokens/**"]
+---
+
+# Design system
+
+- If `DESIGN.md` (and `PRODUCT.md`) exist, follow them. They win over personal taste.
+- Tokens first: use existing color, spacing, radius, typography and motion tokens. No literal hex/rgb,
+  px spacing or ad hoc durations when a token exists. Missing token: add it to the token source, not inline.
+- Every change works in light and dark themes.
+- A11y: semantic elements, visible focus, labels for inputs and icon buttons, contrast >= WCAG AA,
+  keyboard reachable, `prefers-reduced-motion` respected.
+- Reuse existing components before creating one. Do not add a new UI library.
+- Design-system decisions (new token, new component, DESIGN.md change) belong to `/ui`.

package/.claude/rules/web.md

@@ -0,0 +1,27 @@
+---
+paths:
+  - "apps/web/**"
+  - "apps/*web*/**"
+  - "apps/*admin*/**"
+  - "apps/*next*/**"
+  - "**/next.config.*"
+  - "**/app/**/page.tsx"
+  - "**/app/**/layout.tsx"
+  - "**/app/**/route.ts"
+  - "**/app/**/loading.tsx"
+  - "**/app/**/error.tsx"
+  - "**/*.server-action.ts"
+  - "**/app/**/blocks/**"
+  - "**/src/blueprints/**"
+  - "**/*.client.tsx"
+  - "**/*.loader.tsx"
+  - "**/*.revalidate.ts"
+  - "**/middleware.ts"
+  - "**/proxy.ts"
+  - "**/instrumentation.ts"
+---
+
+# Web code
+
+Load skill `arch-web` before changing code here; it owns structure and the references in `arch-web/references/` (services and Server Actions, blocks and RSC composition, cache, auth and session, UI and forms, tests). Implementation is delegated to `/web`.
+For UI or visual work (tokens, components, motion, a11y), delegate to `/ui`; the design skills are preloaded there and are not reachable from here. Mobile-web fixes: `mobile-native`.

package/.claude/settings.json

@@ -0,0 +1,114 @@
+{
+  "subagentPromptCacheTtl": "1h",
+  "env": {
+    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1",
+    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "5"
+  },
+  "worktree": {
+    "baseRef": "head"
+  },
+  "autoCompactWindow": 120000,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/guard-bash.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "Bash|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "graphify hook-guard search",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "graphify hook-guard read",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/orchestrator-guard.sh\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/graphify-update.sh\""
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-budget.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/stop-verify.sh\""
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-compact.sh\""
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-compact.sh\""
+          }
+        ]
+      },
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/config-update-check.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}