claude-code-arcane 2.13.0 → 2.14.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# [2.14.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.13.0...v2.14.0) (2026-10-16)
+
+
+### Features
+
+* **hooks:** leave finished worktrees and tell a session where it is ([df0531f](https://github.com/SebastianLuser/claude-code-arcane/commit/df0531feef6801649682f8f21dfcf36de006851b))
+* **session:** keep the progress file in .claude/session-state ([0615ce5](https://github.com/SebastianLuser/claude-code-arcane/commit/0615ce5289751044a749a034b1ef99bcbfd7e058))
+
 # [2.13.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.12.0...v2.13.0) (2026-10-16)
 
 

package/README.md

@@ -1,6 +1,6 @@
 # Claude Code Arcane
 
-> **437 skills, 115 agents, 16 hooks and 36 rules for Claude Code — selective deploy by profile.**
+> **437 skills, 115 agents, 17 hooks and 36 rules for Claude Code — selective deploy by profile.**
 
 A configuration harness installable via `npx`. Pick a **profile** that matches your stack and only the relevant tools get installed into your project's `.claude/` directory.
 

package/agents/visualnovel/vn-producer.md

@@ -81,7 +81,7 @@ Know who to call for what:
 
 #### Progress Tracking
 
-Maintain `production/session-state/active.md` with:
+Maintain `.claude/session-state/active.md` with:
 
 ```markdown
 ## VN Production State
@@ -122,7 +122,7 @@ Maintain `production/session-state/active.md` with:
 | Audio asset gaps | Medium | Medium | Placeholder tracks, generate late |
 
 ### File Ownership
-- `production/session-state/active.md` — session state
+- `.claude/session-state/active.md` — session state
 - `production/milestones/` — milestone definitions and status
 - `design/assets/asset-manifest.md` — asset pipeline tracking (shared with vn-asset-pipeline)
 

package/dist/cli.js

@@ -926,7 +926,9 @@ function defaultHooks(target) {
     Notification: one("notify.sh", 10),
     PreCompact: one("pre-compact.sh", 10),
     PostCompact: one("post-compact.sh", 10),
-    Stop: one("session-stop.sh", 10),
+    Stop: [
+      { matcher: "", hooks: [hook(target, "session-stop.sh", 10), hook(target, "worktree-stop.sh", 10)] }
+    ],
     SubagentStart: one("log-agent.sh", 5),
     SubagentStop: one("log-agent-stop.sh", 5)
   };
@@ -973,6 +975,13 @@ function healHooks(hooks, target) {
     pre.push({ matcher: FILE_TOOLS_MATCHER, hooks: [hook(target, "guard.sh", 10)] });
     changes.push("guard for file edits");
   }
+  const stop = hooks.Stop ??= [];
+  if (!stop.some((g) => g.hooks?.some((h) => h.command?.includes("worktree-stop.sh")))) {
+    const group = stop.find((g) => !g.matcher);
+    if (group) group.hooks = [...group.hooks ?? [], hook(target, "worktree-stop.sh", 10)];
+    else stop.push({ matcher: "", hooks: [hook(target, "worktree-stop.sh", 10)] });
+    changes.push("worktree exit on stop");
+  }
   return changes;
 }
 

package/docs/USER-GUIDE.md

@@ -2,7 +2,7 @@
 
 ## What is Arcane?
 
-Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **437 skills**, **115 agents**, **16 hooks**, and **36 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
+Arcane is a configuration harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It provides a curated library of **437 skills**, **115 agents**, **17 hooks**, and **36 rules** that you selectively deploy into any project. Instead of shipping everything to every project (wasting tokens and degrading performance), you pick a **profile** that matches your stack and only the relevant tools get installed.
 
 ## Table of Contents
 
@@ -239,7 +239,7 @@ Every installation automatically loads `core.yaml` first:
 |----------|----------|
 | **Skills (21)** | commit, create-pr, changelog, check, code-review, context-prime, help, start, fix-issue, hotfix, brainstorm, scope-check, reverse-document, skill-improve, skill-test, tech-debt, arcane-status, arcane-list, arcane-add, arcane-remove, arcane-clean |
 | **Rules (8)** | data-files, prototype-code, test-standards, implementation-workflow, code-comments, verification, agent-delegation, git-worktrees |
-| **Hooks (15)** | session-start, detect-division, detect-unreal, detect-gaps, check-update, guard, validate-commit, validate-assets, validate-skill-change, notify, pre-compact, post-compact, session-stop, log-agent, log-agent-stop |
+| **Hooks (16)** | session-start, detect-division, detect-unreal, detect-gaps, check-update, guard, validate-commit, validate-assets, validate-skill-change, notify, pre-compact, post-compact, session-stop, worktree-stop, log-agent, log-agent-stop |
 | **Agents (1 dir)** | quality |
 | **Permissions** | 15 allow (git, ls, gh pr/issue/run and read-only gh, curl) + 13 deny (force push, reset --hard, clean -f, sudo, .env, etc.) |
 

package/docs/collaborative-design.md

@@ -311,7 +311,7 @@ Para documentos largos (ADRs, PRDs, GDDs, RFCs) escribí sección por sección a
    - Review con el usuario
    - Iterar hasta aprobación
    - Escribir ESA sección al archivo
-   - Update production/session-state/active.md
+   - Update .claude/session-state/active.md
    - La conversación de esa sección puede compactarse — la decisión ya está en disco
 
 3. Si la sesión crashea mid-document:

package/docs/context-management.md

@@ -16,7 +16,7 @@ Claude Code tiene una ventana de contexto limitada. Sesiones largas llegan al l
 
 ### Session State File
 
-Mantené `production/session-state/active.md` como checkpoint vivo. Update después de cada milestone significativo:
+Mantené `.claude/session-state/active.md` como checkpoint vivo. Update después de cada milestone significativo:
 
 - Sección de diseño / ADR aprobada y escrita
 - Decisión arquitectónica tomada
@@ -25,23 +25,6 @@ Mantené `production/session-state/active.md` como checkpoint vivo. Update despu
 
 El state file debe contener: tarea actual, checklist de progreso, decisiones clave tomadas, archivos en trabajo, preguntas abiertas.
 
-### Status Line Block (opcional, para proyectos activos)
-
-Para proyectos en fase de ejecución, incluir en `active.md` un bloque estructurado que el status line script puede parsear:
-
-```markdown
-<!-- STATUS -->
-Epic: Auth refactor
-Feature: JWT rotation
-Task: Implementar refresh endpoint
-<!-- /STATUS -->
-```
-
-- Los tres campos (Epic, Feature, Task) son opcionales — incluí solo lo aplicable
-- Update cuando cambiás de foco
-- El status line lo muestra como breadcrumb: `Auth refactor > JWT rotation > Refresh endpoint`
-- Remove o vaciá cuando no hay work focus activo
-
 Después de cualquier disrupción (compaction, crash, `/clear`), leé el state file primero.
 
 ---
@@ -71,8 +54,8 @@ Esto mantiene el context window con ~3-5k tokens (solo la sección actual) en ve
 
 ### Compaction Hooks
 
-- `pre-compact.sh`: Guarda summary del estado antes de compaction
-- `post-compact.sh`: Carga summary después de compaction
+- `pre-compact.sh` y `post-compact.sh` solo anotan la hora en `.claude/session-state/sessions.log`. No guardan ni cargan estado.
+- Lo que sobrevive a la compactación es el archivo: `session-start.sh` corre también después de cada compactación (SessionStart con matcher vacío) y muestra el inicio de `active.md`. Por eso `active.md` tiene que estar al día **antes** de compactar.
 
 ---
 
@@ -111,7 +94,7 @@ Los subagents no heredan historia de conversación — dales contexto completo e
 
 Cuando el contexto se compacta, preservá en el summary:
 
-- Referencia a `production/session-state/active.md` (leer para recover state)
+- Referencia a `.claude/session-state/active.md` (leer para recover state)
 - Lista de archivos modificados en la sesión y su propósito
 - Decisiones arquitectónicas hechas y su rationale
 - Tasks activas del sprint y estado actual
@@ -163,7 +146,7 @@ Cuando el status line muestra >= 70%:
 ```
 Tarea: "Implementá auth JWT completo"
 
-1. Crear production/session-state/active.md con:
+1. Crear .claude/session-state/active.md con:
    - Feature: JWT auth
    - Files to create: src/auth/{tokens.ts, middleware.ts, login.ts}
    - Tests: tests/auth.test.ts

package/docs/coordination-rules.md

@@ -71,7 +71,7 @@ Ningún agente hace commits sin instrucción explícita del user. Ni siquiera el
 
 ## Regla #9 — Session State
 
-Actualizar `production/session-state/active.md` cuando:
+Actualizar `.claude/session-state/active.md` cuando:
 - Se completa un section/phase
 - Se toma una decisión significativa
 - Se cambia de división/agente

package/docs/directory-structure.md

@@ -97,9 +97,9 @@ claude-code-arcane/
 │   ├── statusline.sh                  # Solo con el profile statusline
 │   ├── output-styles/                 # Solo si algún profile declara output_styles
 │   ├── docs/                          # Copia de docs/; arcane update la mantiene al día
+│   ├── session-state/                 # active.md y logs de sesión; se ignora solo (.gitignore con *)
 │   └── .arcane-trash/                 # Lo que arcane update saca; nunca se borra con rm
-├── .claude.bak/                       # Backup de .claude/ antes de instalar
-└── production/session-state/          # Estado de sesión que escriben los hooks
+└── .claude.bak/                       # Backup de .claude/ antes de instalar
 ```
 
 Fuera del proyecto, `~/.arcane/` guarda el registro de instalaciones (`installations.json`) y el contenido descargado de GitHub (`cache/<version>/`). `ARCANE_HOME` lo desvía.
@@ -127,7 +127,7 @@ Los eventos los define `src/installer.ts` al generar `settings.json`, no los pro
 | PostToolUse (`Write\|Edit`) | `validate-assets.sh`, `validate-skill-change.sh` |
 | Notification | `notify.sh` |
 | PreCompact / PostCompact | `pre-compact.sh` / `post-compact.sh` |
-| Stop | `session-stop.sh` |
+| Stop | `session-stop.sh`, `worktree-stop.sh` |
 | SubagentStart / SubagentStop | `log-agent.sh` / `log-agent-stop.sh` |
 
 Cada comando es `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/<script>"`: dentro de un worktree los hooks corren parados en el worktree, que puede no tener `.claude/hooks/` commiteado, y la variable siempre apunta al proyecto donde arrancó la sesión. `arcane update` migra las instalaciones que tenían la ruta relativa.

package/docs/gates/README.md

@@ -123,8 +123,8 @@ Después de que un gate resuelve, registrar el verdict en el header de status de
 ```
 
 Para phase gates, registrar en:
-- Software: `docs/architecture/architecture.md` o `production/session-state/active.md`
-- Gamedev: `docs/architecture/architecture.md` o `production/session-state/active.md`
+- Software: `docs/architecture/architecture.md` o `.claude/session-state/active.md`
+- Gamedev: `docs/architecture/architecture.md` o `.claude/session-state/active.md`
 
 ---
 

package/hooks/detect-division.sh

@@ -22,7 +22,7 @@ main() {
     DIVISION="engineering (Python)"
   fi
 
-  [[ -d "production/session-state" ]] && echo "Division: $DIVISION" > production/session-state/division.txt
+  [[ -d ".claude/session-state" ]] && echo "Division: $DIVISION" > .claude/session-state/division.txt
 }
 main 2>/dev/null
 exit 0

package/hooks/log-agent-stop.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] subagent_stop" >> production/session-state/agents.log
+  [[ -d .claude/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] subagent_stop" >> .claude/session-state/agents.log
 }
 main 2>/dev/null
 exit 0

package/hooks/log-agent.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] subagent_start" >> production/session-state/agents.log
+  [[ -d .claude/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] subagent_start" >> .claude/session-state/agents.log
 }
 main 2>/dev/null
 exit 0

package/hooks/notify.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] notification" >> production/session-state/notifications.log
+  [[ -d .claude/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] notification" >> .claude/session-state/notifications.log
 }
 main 2>/dev/null
 exit 0

package/hooks/post-compact.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] post-compact" >> production/session-state/sessions.log
+  [[ -d .claude/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] post-compact" >> .claude/session-state/sessions.log
 }
 main 2>/dev/null
 exit 0

package/hooks/pre-compact.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] pre-compact" >> production/session-state/sessions.log
+  [[ -d .claude/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] pre-compact" >> .claude/session-state/sessions.log
 }
 main 2>/dev/null
 exit 0

package/hooks/session-start.sh

@@ -3,13 +3,49 @@
 # Graceful: wraps in main(), never blocks session
 set +e
 
-main() {
-  mkdir -p production/session-state 2>/dev/null
+STATE_DIR=".claude/session-state"
+LEGACY_STATE_DIR="production/session-state"
+
+# The folder holds session notes, never project files: a .gitignore with `*` keeps it
+# out of every commit without touching the project's own .gitignore.
+ensure_state_dir() {
+  mkdir -p "$STATE_DIR" 2>/dev/null
+  [ -f "$STATE_DIR/.gitignore" ] || echo '*' > "$STATE_DIR/.gitignore" 2>/dev/null
+}
+
+# active.md used to live in production/session-state/. Move it once, so a task left
+# half done before the update still shows up here.
+migrate_legacy_state() {
+  [ -f "$LEGACY_STATE_DIR/active.md" ] || return 0
+  [ -f "$STATE_DIR/active.md" ] && return 0
+  ensure_state_dir
+  mv "$LEGACY_STATE_DIR/active.md" "$STATE_DIR/active.md" 2>/dev/null &&
+    echo "Moved $LEGACY_STATE_DIR/active.md to $STATE_DIR/active.md"
+}
 
-  SESSION_LOG="production/session-state/sessions.log"
-  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Session started" >> "$SESSION_LOG" 2>/dev/null
+# A session started inside a worktree should know it, and where the main checkout is.
+worktree_notice() {
+  local DIRS GIT_DIR COMMON_DIR TOP BRANCH MAIN MAIN_BRANCH
+  DIRS=$(git rev-parse --path-format=absolute --git-dir --git-common-dir 2>/dev/null) || return 0
+  GIT_DIR=$(echo "$DIRS" | sed -n 1p)
+  COMMON_DIR=$(echo "$DIRS" | sed -n 2p)
+  [ -z "$COMMON_DIR" ] || [ "$GIT_DIR" = "$COMMON_DIR" ] && return 0
+  TOP=$(git rev-parse --show-toplevel 2>/dev/null)
+  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+  MAIN=$(dirname "$COMMON_DIR")
+  MAIN_BRANCH=$(git -C "$MAIN" rev-parse --abbrev-ref HEAD 2>/dev/null)
+  echo "Worktree: you are in $TOP on branch $BRANCH."
+  echo "Main checkout: $MAIN on branch $MAIN_BRANCH. See the git-worktrees rule before pulling or switching branches."
+  echo ""
+}
+
+main() {
+  migrate_legacy_state
+  [ -d "$STATE_DIR" ] && ensure_state_dir
+  [ -d "$STATE_DIR" ] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Session started" >> "$STATE_DIR/sessions.log" 2>/dev/null
 
   echo "=== Claude Code Arcane — Session Context ==="
+  worktree_notice
 
   BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
   if [ -n "$BRANCH" ]; then
@@ -55,7 +91,7 @@ main() {
     fi
   fi
 
-  STATE_FILE="production/session-state/active.md"
+  STATE_FILE="$STATE_DIR/active.md"
   if [ -f "$STATE_FILE" ]; then
     echo ""
     echo "=== ACTIVE SESSION STATE DETECTED ==="

package/hooks/session-stop.sh

@@ -1,7 +1,11 @@
 #!/usr/bin/env bash
 set +e
 main() {
-  [[ -d production/session-state ]] && echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Session stopped" >> production/session-state/sessions.log
+  [[ -d .claude/session-state ]] || return 0
+  # Claude creates the folder the first time it writes active.md; keep it out of
+  # commits from that same turn on.
+  [[ -f .claude/session-state/.gitignore ]] || echo '*' > .claude/session-state/.gitignore
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Session stopped" >> .claude/session-state/sessions.log
 }
 main 2>/dev/null
 exit 0

package/hooks/worktree-stop.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Hook: worktree-stop.sh — Stop
+#
+# A session that enters a worktree with EnterWorktree tends to stay there after the
+# task is done, and the next pull or branch switch fails inside it. When the turn
+# ends inside such a worktree with everything committed, block the stop once and ask
+# Claude to leave with ExitWorktree (keep), or to say the task continues.
+#
+# Fires once per commit: a new commit means new progress, so it may ask again.
+# Never fires when the session itself started inside the worktree (ExitWorktree
+# could not leave it) or while there are uncommitted changes (work in progress).
+set +e
+
+main() {
+  local INPUT PROJECT TOP BRANCH HEAD MARKER_DIR MARKER REASON
+  INPUT=$(cat 2>/dev/null)
+  # Second stop of the same turn: Claude already answered the block.
+  echo "$INPUT" | grep -qE '"stop_hook_active"[[:space:]]*:[[:space:]]*true' && return 0
+
+  PROJECT="${CLAUDE_PROJECT_DIR:-}"
+  [ -n "$PROJECT" ] || return 0
+  TOP=$(git rev-parse --show-toplevel 2>/dev/null) || return 0
+
+  # Only worktrees EnterWorktree creates: under the project the session started in.
+  case "$TOP" in
+    "$PROJECT"/.claude/worktrees/*) ;;
+    *) return 0 ;;
+  esac
+
+  [ -z "$(git status --porcelain 2>/dev/null)" ] || return 0
+
+  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+  HEAD=$(git rev-parse HEAD 2>/dev/null)
+  MARKER_DIR="$PROJECT/.claude/session-state"
+  MARKER="$MARKER_DIR/.worktree-stop"
+  [ "$(cat "$MARKER" 2>/dev/null)" = "$TOP $HEAD" ] && return 0
+  mkdir -p "$MARKER_DIR" 2>/dev/null
+  [ -f "$MARKER_DIR/.gitignore" ] || echo '*' > "$MARKER_DIR/.gitignore"
+  echo "$TOP $HEAD" > "$MARKER"
+
+  REASON="You are still inside the worktree $TOP (branch $BRANCH) and its changes are committed. If the task is finished, push the branch if the task included pushing, then leave with ExitWorktree (action: keep) and tell the user the worktree path and branch. If the task continues, say so in one line and stop."
+  REASON=${REASON//\\/\/}
+  REASON=${REASON//\"/\'}
+  printf '{"decision": "block", "reason": "%s"}\n' "$REASON"
+}
+
+main
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx claude-code-arcane",
   "type": "module",
   "bin": {

package/profiles/core.yaml

@@ -57,6 +57,7 @@ hooks:
   - pre-compact.sh
   - post-compact.sh
   - session-stop.sh
+  - worktree-stop.sh
   - log-agent.sh
   - log-agent-stop.sh
 

package/rules/implementation-workflow.md

@@ -39,6 +39,30 @@ Use AskUserQuestion exactly like this:
 - **Goal-driven:** Help the user define a verifiable goal statement and 2-4 checkpoints, create tasks, implement toward each checkpoint. No formal plan.
 - **Directo:** Proceed immediately without ceremony.
 
+## Progress file
+
+In **Plan + Goal** and **Goal-driven** mode, keep `.claude/session-state/active.md` up to date. A compaction or a new session loses the conversation, not this file: `session-start.sh` shows its first lines when a session starts and after every compaction.
+
+- **Create it** when the goal is set. If `.claude/session-state/` does not exist yet, create it with a `.gitignore` containing `*`, so the file never lands in a commit.
+- **Update it** at every checkpoint, and always before a compaction.
+- **Close it** when the task ends: set `Status: closed` and record the final verification result.
+- Keep it under 30 lines:
+
+```markdown
+# <task>
+Status: in progress | closed
+Goal: <verifiable outcome>
+Criteria: <how we know it is done>
+Plan:
+- [x] <step done>
+- [ ] <step pending>
+Decisions: <decision> — <why>
+Next: <the next concrete step>
+Not verified: <what has not been checked yet>
+```
+
+Directo and Action Plan tasks do not need it.
+
 ## Before writing new code
 
 In every mode, search in this order and take the first option that fully works:

package/skills/help/SKILL.md

@@ -14,7 +14,7 @@ model: haiku
 
 - Stage: !`cat production/stage.txt 2>/dev/null | tr -d '[:space:]' || echo 'not set'`
 - Latest sprint: !`ls -t production/sprints/*.md 2>/dev/null | head -1 || echo 'none'`
-- Session state: !`head -5 production/session-state/active.md 2>/dev/null || echo 'none'`
+- Session state: !`head -5 .claude/session-state/active.md 2>/dev/null || echo 'none'`
 
 Read-only skill — reports findings, writes no files. Lightweight orientation; for a formal readiness check use `/gate-check`.
 
@@ -29,7 +29,7 @@ Read `.claude/docs/workflow-catalog.yaml` (authoritative phases/steps). Glob `.c
 
 ## Step 3: Read Session Context
 
-Read `production/session-state/active.md` — what was most recently worked on, in-progress tasks, open questions.
+Read `.claude/session-state/active.md` — what was most recently worked on, in-progress tasks, open questions.
 
 ## Step 4: Check Step Completion
 

package/skills/start/SKILL.md

@@ -12,7 +12,7 @@ Entry point para sesiones nuevas. Detecta contexto, hace preguntas clave, rutea
 
 ## Paso 1: Detectar contexto
 
-Escanear en paralelo: Unity (`ProjectSettings/ProjectVersion.txt`), Unreal (`*.uproject`), Web/Node (`package.json`), Go (`go.mod`), Python (`pyproject.toml`/`requirements.txt`), Flutter (`pubspec.yaml`), Rust (`Cargo.toml`), docs (`README.md`, `CLAUDE.md`, `design/`, `docs/`), session state (`production/session-state/active.md`).
+Escanear en paralelo: Unity (`ProjectSettings/ProjectVersion.txt`), Unreal (`*.uproject`), Web/Node (`package.json`), Go (`go.mod`), Python (`pyproject.toml`/`requirements.txt`), Flutter (`pubspec.yaml`), Rust (`Cargo.toml`), docs (`README.md`, `CLAUDE.md`, `design/`, `docs/`), session state (`.claude/session-state/active.md`).
 
 ## Paso 2: Determinar etapa
 
@@ -45,7 +45,7 @@ AskUserQuestion multi-tab:
 
 ## Paso 5: Set session state
 
-Crear `production/session-state/active.md`: project name, division, stage, user role, next action, stack detected, existing artifacts, recommended flow (3 commands).
+Crear `.claude/session-state/active.md`: project name, division, stage, user role, next action, stack detected, existing artifacts, recommended flow (3 commands).
 
 ## Paso 6: First action
 

package/skills/story-done/SKILL.md

@@ -12,7 +12,7 @@ Closes loop between design and implementation. Verifies acceptance criteria, che
 
 ## Phase 1: Find Story
 
-Resolve review mode: `--review` arg → `production/review-mode.txt` → default `lean`. Story source: arg path → `production/session-state/active.md` → most recent sprint file (IN PROGRESS stories) → AskUserQuestion.
+Resolve review mode: `--review` arg → `production/review-mode.txt` → default `lean`. Story source: arg path → `.claude/session-state/active.md` → most recent sprint file (IN PROGRESS stories) → AskUserQuestion.
 
 ## Phase 2: Read Story
 
@@ -55,7 +55,7 @@ BLOCKED → do not proceed, list fixes, offer help.
 
 ## Phase 7: Update Story
 
-Ask approval → edit story: `Status: Complete` + `## Completion Notes` (date, criteria, deviations, test evidence, code review status). Advisory deviations → offer to log in `docs/tech-debt-register.md`. Update `production/sprint-status.yaml` if exists. Append to `production/session-state/active.md`.
+Ask approval → edit story: `Status: Complete` + `## Completion Notes` (date, criteria, deviations, test evidence, code review status). Advisory deviations → offer to log in `docs/tech-debt-register.md`. Update `production/sprint-status.yaml` if exists. Append to `.claude/session-state/active.md`.
 
 ## Phase 8: Surface Next Story
 

package/skills/ux-design/SKILL.md

@@ -38,7 +38,7 @@ If output file exists → read it, show section status table (Complete/Empty/Pla
 
 ## Skeleton Creation
 
-Create output file with `[To be designed]` placeholders for all sections. Update `production/session-state/active.md`.
+Create output file with `[To be designed]` placeholders for all sections. Update `.claude/session-state/active.md`.
 
 > → Read references/spec-sections.md for [section inventories for UX spec, HUD, pattern library, and key section guidance]