From ed42fe2cd4a35dcb026d1284ce2c017e204a5d92 Mon Sep 17 00:00:00 2001
From: Yasuhiro Fujii <yasuhiro.fujii@medley.jp>
Date: Thu, 26 Mar 2026 09:02:35 +0900
Subject: [PATCH 1/2] fix: generate claude runtime under install root

---
 scripts/gen-skill-docs.ts   | 10 +++++++++-
 setup                       | 37 ++++++++++++++++++++++++++++++++++++-
 test/gen-skill-docs.test.ts | 17 +++++++++++++++++
 3 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts
index 8d483dad28..21dd1e9c56 100644
--- a/scripts/gen-skill-docs.ts
+++ b/scripts/gen-skill-docs.ts
@@ -22,6 +22,9 @@ import { generatePlanCompletionAuditShip, generatePlanCompletionAuditReview, gen
 
 const ROOT = path.resolve(import.meta.dir, '..');
 const DRY_RUN = process.argv.includes('--dry-run');
+const OUTPUT_ROOT = process.env.GSTACK_SKILL_OUT_ROOT
+  ? path.resolve(process.env.GSTACK_SKILL_OUT_ROOT)
+  : null;
 
 // ─── Host Detection ─────────────────────────────────────────
 
@@ -2972,7 +2975,10 @@ const GENERATED_HEADER = `<!-- AUTO-GENERATED from {{SOURCE}} — do not edit di
 function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath: string; content: string } {
   const tmplContent = fs.readFileSync(tmplPath, 'utf-8');
   const relTmplPath = path.relative(ROOT, tmplPath);
-  let outputPath = tmplPath.replace(/\.tmpl$/, '');
+  const defaultOutputPath = tmplPath.replace(/\.tmpl$/, '');
+  let outputPath = OUTPUT_ROOT && host === 'claude'
+    ? path.join(OUTPUT_ROOT, path.relative(ROOT, defaultOutputPath))
+    : defaultOutputPath;
 
   // Determine skill directory relative to ROOT
   const skillDir = path.relative(ROOT, path.dirname(tmplPath));
@@ -2987,6 +2993,8 @@ function processTemplate(tmplPath: string, host: Host = 'claude'): { outputPath:
     outputPath = path.join(outputDir, 'SKILL.md');
   }
 
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+
   // Extract skill name from frontmatter for TemplateContext
   const { name: extractedName, description: extractedDescription } = extractNameAndDescription(tmplContent);
   const skillName = extractedName || path.basename(path.dirname(tmplPath));
diff --git a/setup b/setup
index bfae87851c..778bd47c49 100755
--- a/setup
+++ b/setup
@@ -221,6 +221,37 @@ link_claude_skill_dirs() {
   fi
 }
 
+create_claude_runtime_root() {
+  local repo_root="$1"
+  local runtime_root="$2"
+  mkdir -p "$runtime_root"
+
+  (
+    cd "$repo_root"
+    GSTACK_SKILL_OUT_ROOT="$runtime_root" bun run scripts/gen-skill-docs.ts >/dev/null
+  )
+
+  for asset in bin browse review qa; do
+    local src="$repo_root/$asset"
+    local dst="$runtime_root/$asset"
+    if [ -d "$src" ] || [ -f "$src" ]; then
+      if [ -L "$dst" ] || [ ! -e "$dst" ]; then
+        ln -snf "$src" "$dst"
+      fi
+    fi
+  done
+
+  for file in ETHOS.md; do
+    local src="$repo_root/$file"
+    local dst="$runtime_root/$file"
+    if [ -f "$src" ]; then
+      if [ -L "$dst" ] || [ ! -e "$dst" ]; then
+        ln -snf "$src" "$dst"
+      fi
+    fi
+  done
+}
+
 # ─── Helper: link generated Codex skills into a skills parent directory ──
 # Installs from .agents/skills/gstack-* (the generated Codex-format skills)
 # instead of source dirs (which have Claude paths).
@@ -348,7 +379,11 @@ fi
 
 if [ "$INSTALL_CLAUDE" -eq 1 ]; then
   if [ "$SKILLS_BASENAME" = "skills" ]; then
-    link_claude_skill_dirs "$SOURCE_GSTACK_DIR" "$INSTALL_SKILLS_DIR"
+    CLAUDE_RUNTIME_ROOT="$INSTALL_SKILLS_DIR/gstack"
+    if [ "$INSTALL_GSTACK_DIR" != "$CLAUDE_RUNTIME_ROOT" ]; then
+      create_claude_runtime_root "$SOURCE_GSTACK_DIR" "$CLAUDE_RUNTIME_ROOT"
+    fi
+    link_claude_skill_dirs "$CLAUDE_RUNTIME_ROOT" "$INSTALL_SKILLS_DIR"
     if [ "$LOCAL_INSTALL" -eq 1 ]; then
       echo "gstack ready (project-local)."
       echo "  skills: $INSTALL_SKILLS_DIR"
diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts
index d8a071a1f7..1d0b83ecdc 100644
--- a/test/gen-skill-docs.test.ts
+++ b/test/gen-skill-docs.test.ts
@@ -1478,6 +1478,23 @@ describe('setup script validation', () => {
     expect(fnBody).toContain('ln -snf "gstack/$skill_name"');
   });
 
+  test('Claude install links skills from the generated runtime root', () => {
+    const claudeSection = setupContent.slice(
+      setupContent.indexOf('# 4. Install for Claude'),
+      setupContent.indexOf('# 5. Install for Codex')
+    );
+    expect(claudeSection).toContain('CLAUDE_RUNTIME_ROOT="$INSTALL_SKILLS_DIR/gstack"');
+    expect(claudeSection).toContain('link_claude_skill_dirs "$CLAUDE_RUNTIME_ROOT" "$INSTALL_SKILLS_DIR"');
+  });
+
+  test('create_claude_runtime_root runs generator from the source repo root', () => {
+    const fnStart = setupContent.indexOf('create_claude_runtime_root()');
+    const fnEnd = setupContent.indexOf('}', setupContent.indexOf('for asset in', fnStart));
+    const fnBody = setupContent.slice(fnStart, fnEnd);
+    expect(fnBody).toContain('cd "$repo_root"');
+    expect(fnBody).toContain('GSTACK_SKILL_OUT_ROOT="$runtime_root" bun run scripts/gen-skill-docs.ts');
+  });
+
   test('setup supports --host auto|claude|codex|kiro', () => {
     expect(setupContent).toContain('--host');
     expect(setupContent).toContain('claude|codex|kiro|auto');

From 46b7cd6643cad4fa203d2b933828a4a630cc7740 Mon Sep 17 00:00:00 2001
From: Yasuhiro Fujii <yasuhiro.fujii@medley.jp>
Date: Thu, 26 Mar 2026 09:04:15 +0900
Subject: [PATCH 2/2] fix: infer claude install root from setup location

---
 setup                       | 52 ++++++++++++++++++++++++++++++-------
 test/gen-skill-docs.test.ts | 13 ++++++++++
 2 files changed, 56 insertions(+), 9 deletions(-)

diff --git a/setup b/setup
index 778bd47c49..c4cbdd35a7 100755
--- a/setup
+++ b/setup
@@ -12,6 +12,8 @@ INSTALL_GSTACK_DIR="$(cd "$(dirname "$0")" && pwd)"
 SOURCE_GSTACK_DIR="$(cd "$(dirname "$0")" && pwd -P)"
 INSTALL_SKILLS_DIR="$(dirname "$INSTALL_GSTACK_DIR")"
 BROWSE_BIN="$SOURCE_GSTACK_DIR/browse/dist/browse"
+GLOBAL_CLAUDE_SKILLS_DIR="$HOME/.claude/skills"
+GLOBAL_CLAUDE_GSTACK_DIR="$GLOBAL_CLAUDE_SKILLS_DIR/gstack"
 CODEX_SKILLS="$HOME/.codex/skills"
 CODEX_GSTACK="$CODEX_SKILLS/gstack"
 
@@ -22,12 +24,14 @@ esac
 
 # ─── Parse flags ──────────────────────────────────────────────
 HOST="claude"
-LOCAL_INSTALL=0
+FORCE_GLOBAL=0
+FORCE_LOCAL=0
 while [ $# -gt 0 ]; do
   case "$1" in
     --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, or auto)" >&2 && exit 1; HOST="$2"; shift 2 ;;
     --host=*) HOST="${1#--host=}"; shift ;;
-    --local) LOCAL_INSTALL=1; shift ;;
+    --global) FORCE_GLOBAL=1; shift ;;
+    --local) FORCE_LOCAL=1; shift ;;
     *) shift ;;
   esac
 done
@@ -37,18 +41,48 @@ case "$HOST" in
   *) echo "Unknown --host value: $HOST (expected claude, codex, kiro, or auto)" >&2; exit 1 ;;
 esac
 
-# --local: install to .claude/skills/ in the current working directory
-if [ "$LOCAL_INSTALL" -eq 1 ]; then
+CLAUDE_PROJECT_LOCAL=0
+infer_claude_install_dir() {
+  if [ "$FORCE_GLOBAL" -eq 1 ]; then
+    INSTALL_SKILLS_DIR="$GLOBAL_CLAUDE_SKILLS_DIR"
+    CLAUDE_PROJECT_LOCAL=0
+    return
+  fi
+
+  if [ "$FORCE_LOCAL" -eq 1 ]; then
+    INSTALL_SKILLS_DIR="$(pwd)/.claude/skills"
+    CLAUDE_PROJECT_LOCAL=1
+    return
+  fi
+
+  case "$INSTALL_GSTACK_DIR" in
+    "$GLOBAL_CLAUDE_GSTACK_DIR")
+      INSTALL_SKILLS_DIR="$GLOBAL_CLAUDE_SKILLS_DIR"
+      CLAUDE_PROJECT_LOCAL=0
+      ;;
+    */.claude/skills/gstack)
+      INSTALL_SKILLS_DIR="$(dirname "$INSTALL_GSTACK_DIR")"
+      CLAUDE_PROJECT_LOCAL=1
+      ;;
+    *)
+      INSTALL_SKILLS_DIR="$GLOBAL_CLAUDE_SKILLS_DIR"
+      CLAUDE_PROJECT_LOCAL=0
+      ;;
+  esac
+}
+
+infer_claude_install_dir
+
+if [ "$CLAUDE_PROJECT_LOCAL" -eq 1 ]; then
   if [ "$HOST" = "codex" ]; then
-    echo "Error: --local is only supported for Claude Code (not Codex)." >&2
+    echo "Error: project-local install is only supported for Claude Code (not Codex). Use --global with --host codex if needed." >&2
     exit 1
   fi
-  INSTALL_SKILLS_DIR="$(pwd)/.claude/skills"
-  mkdir -p "$INSTALL_SKILLS_DIR"
   HOST="claude"
-  INSTALL_CODEX=0
 fi
 
+mkdir -p "$INSTALL_SKILLS_DIR"
+
 # For auto: detect which agents are installed
 INSTALL_CLAUDE=0
 INSTALL_CODEX=0
@@ -384,7 +418,7 @@ if [ "$INSTALL_CLAUDE" -eq 1 ]; then
       create_claude_runtime_root "$SOURCE_GSTACK_DIR" "$CLAUDE_RUNTIME_ROOT"
     fi
     link_claude_skill_dirs "$CLAUDE_RUNTIME_ROOT" "$INSTALL_SKILLS_DIR"
-    if [ "$LOCAL_INSTALL" -eq 1 ]; then
+    if [ "$CLAUDE_PROJECT_LOCAL" -eq 1 ]; then
       echo "gstack ready (project-local)."
       echo "  skills: $INSTALL_SKILLS_DIR"
     else
diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts
index 1d0b83ecdc..5c0ac74774 100644
--- a/test/gen-skill-docs.test.ts
+++ b/test/gen-skill-docs.test.ts
@@ -1456,6 +1456,19 @@ describe('setup script validation', () => {
     expect(setupContent).toContain('link_codex_skill_dirs "$SOURCE_GSTACK_DIR" "$CODEX_SKILLS"');
   });
 
+  test('Claude install infers project-local vs global from setup location, not pwd', () => {
+    expect(setupContent).toContain('infer_claude_install_dir()');
+    expect(setupContent).toContain('*/.claude/skills/gstack)');
+    expect(setupContent).toContain('INSTALL_SKILLS_DIR="$GLOBAL_CLAUDE_SKILLS_DIR"');
+  });
+
+  test('setup keeps explicit --local and --global overrides', () => {
+    expect(setupContent).toContain('--local');
+    expect(setupContent).toContain('--global');
+    expect(setupContent).toContain('FORCE_GLOBAL=1');
+    expect(setupContent).toContain('FORCE_LOCAL=1');
+  });
+
   test('Codex installs always create sidecar runtime assets for the real skill target', () => {
     expect(setupContent).toContain('if [ "$INSTALL_CODEX" -eq 1 ]; then');
     expect(setupContent).toContain('create_agents_sidecar "$SOURCE_GSTACK_DIR"');