@jenga-ai/agent 1.3.0 → 2.0.0

package/skills/j-init/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: j:j-init
+description: Polyfill alias of the init skill under a collision-safe directory name. Identical behavior to /init — initializes a new project with the standard directory structure, PROJECT_SUMMARY.md, workflow.json, git repo, and gitignore. Use when the built-in "/init" command (e.g. GH Copilot's own init) shadows Jenga's /init alias.
+keywords:
+  - init
+  - initialize
+  - setup
+  - new project
+  - scaffold
+  - j-init
+  - polyfill
+examples:
+  - "initialize a new project"
+  - "set up a new workspace"
+  - "j-init"
+---
+
+# J-Init — Project Setup (polyfill alias of Init)
+
+This skill is a literal-directory-name duplicate of `skills/init/`. It exists because
+some host tools/harnesses (e.g. GH Copilot) ship their own built-in command literally
+named `/init`, which can shadow or override Jenga AI's own `/init` alias (Claude Code's
+native skill resolution is a literal-string, directory-name-based match — see
+`docs/skill-authoring.md`'s "Invocation Convention"). `/j-init` (and `j:j-init`) give
+users a guaranteed-unshadowed way to reach the exact same setup flow.
+
+Keep this file's instructions in lockstep with `skills/init/SKILL.md` — any change made
+there should be mirrored here.
+
+## Instructions
+
+Follow these steps in order. Do not skip steps — the sequence matters.
+
+### 1. Detect existing project state
+
+Before asking anything or scaffolding anything, classify the target directory
+(the current directory) by running the detection script:
+
+```bash
+skills/j-init/scripts/detect-existing-codebase.sh .
+```
+
+It prints exactly one verdict on stdout:
+
+| Verdict | Meaning | What to do |
+|---|---|---|
+| `empty` | The directory is empty, or contains only `.git`, `.gitignore`, and top-level `README*`/`LICENSE*` boilerplate. | Proceed to step 2 — behaviour here is unchanged from before this detection step existed. |
+| `already-scaffolded` | `project/board/`, `project/PROJECT_SUMMARY.md`, or `project/configs/workflow.json` already exists. | Tell the user this directory already has a Jenga scaffold and **stop** — do not run the scaffold script. Re-running it would silently overwrite `PROJECT_SUMMARY.md` and `workflow.json` with fresh stubs. Point them at `/continue` or `/status` instead. |
+| `existing-codebase` | The directory has real content (source, configs, docs beyond the boilerplate list) and is not already scaffolded. | **Pause. Do not scaffold.** Present the choice below and wait for an answer. |
+
+On `existing-codebase`, present this choice verbatim, per the Interaction Pattern in
+`CLAUDE.md` (numbered, free-text last):
+
+    This directory already contains code that wasn't built through Jenga. How would
+    you like to proceed?
+    1. Run /uncharted onboard first, to analyze the existing code and backfill the
+       board before scaffolding
+    2. Scaffold fresh anyway, leaving the board empty (the existing code is never
+       modified either way — onboard mode and fresh scaffolding are both board-only)
+    3. Abort — don't scaffold, don't run /uncharted
+    4. Other (describe below)
+
+- **Option 1** — invoke `/uncharted onboard`. It analyzes the existing code and backfills
+  the board; it never modifies, moves, or restructures application code. Once it
+  finishes, the directory now has `project/PROJECT_SUMMARY.md` etc., so re-running this
+  detection step returns `already-scaffolded` — there is nothing left to scaffold.
+- **Option 2** — continue to step 2 and scaffold fresh. Note in your response that the
+  board will start empty despite the directory containing pre-existing code, since the
+  user explicitly chose that.
+- **Option 3** — stop here. Do not run the scaffold script and do not invoke `/uncharted`.
+- **Option 4** — handle the free-text response on its own merits.
+
+If the run is non-interactive (no user available to answer), default to **option 3
+(abort)**. Unlike the visibility question in step 2, none of these three choices is a
+no-op: running `/uncharted onboard` unattended commits an analysis pass the user never
+asked for, and scaffolding fresh unattended silently discards pre-existing code from the
+board exactly as `/init` did before this step existed. Aborting is the only choice that
+changes nothing on disk, so it is the only safe default.
+
+Never treat `existing-codebase` as if it were `empty`, and never skip straight to step 2
+on that verdict without the user (or the non-interactive default) choosing to.
+
+### 2. Ask how Jenga AI's working files should appear
+
+Ask the user this question, verbatim, before running any script:
+
+    How should Jenga AI's own working files (project/ — the scrum board, todo.md,
+    queue/, rapports/, and logs/) appear in this project?
+    1. Visible — keep them at `project/`, tracked and visible in directory listings
+    2. Ignored — keep them at `project/` but add them to `.gitignore` so they are never committed
+    3. Not sure — explain the trade-offs and ask me again
+
+If the user picks option 3, explain the trade-offs and re-ask. Do not proceed until
+the answer is one of `visible` or `ignored`.
+
+If the run is non-interactive (no user available to answer), use the default:
+**`visible`**. It is the only choice that changes nothing on disk, so an unattended
+run can never silently relocate directories or edit `.gitignore`.
+
+> A third mode, `hidden` (dot-prefixing `project/` to `.project/`, matching the
+> `.agents/`/`.claude/` convention), was built and then withdrawn before release —
+> testing found it left board resolution and session-end hooks writing to two
+> different trees. It is not offered here. See
+> `skills/distribute/CONFIG_SCHEMA.md` for the root-cause note and the tracked
+> follow-up to reintroduce it once fixed.
+
+Carry the chosen value into step 3. Do not apply it yourself — the script owns all
+of the mechanical work.
+
+### 3. Run the scaffold script
+
+`init.sh` is not guaranteed to live at a single fixed path: in a project that
+installed Jenga via npm, it was mirrored to `.claude/skills/j-init/scripts/`
+(Claude Code) and `.agents/skills/j-init/scripts/` (Copilot/other agents) by
+`postinstall.js`, and neither of those exists yet in this framework's own
+source checkout, where it lives at the bare `skills/j-init/scripts/` path
+instead. This step runs before `CLAUDE.md`/`AGENTS.md` exist, so it cannot
+rely on either file's routing instructions to resolve the path — it must
+locate its own script directly. Execute the init script from the project
+root, passing the choice from step 2:
+
+```bash
+INIT_SCRIPT=""
+for candidate in .claude/skills/j-init/scripts/init.sh .agents/skills/j-init/scripts/init.sh skills/j-init/scripts/init.sh; do
+  [[ -f "$candidate" ]] && { INIT_SCRIPT="$candidate"; break; }
+done
+if [[ -z "$INIT_SCRIPT" ]]; then
+  echo "Error: could not locate init.sh under .claude/skills/, .agents/skills/, or skills/" >&2
+  exit 1
+fi
+chmod +x "$INIT_SCRIPT" && "$INIT_SCRIPT" --visibility <visible|ignored>
+```
+
+Omitting `--visibility` falls back to the `JENGA_PROJECT_FILES_VISIBILITY`
+environment variable, then to `visible`.
+
+This script handles all scaffolding in one step:
+1. Initializes the git repository
+2. Creates `.gitignore`
+3. Creates the full directory structure under `project/`
+4. Creates `project/PROJECT_SUMMARY.md` with placeholder content
+5. Creates `project/configs/workflow.json` with shared constants
+6. Creates `project/configs/test-config.json` stub
+7. Creates `project/configs/scope-thresholds.json` with default execution-scope thresholds (consumed by `/jenga` and `/do`, which halt if it's missing)
+8. Creates `project/data/baselines.json`
+9. Creates `project/logs/events.json`
+10. Creates `docs/STRATEGY.md` — a strategic brief stub intended for investors, partners, and the product team
+11. Creates `CHANGELOG.md` from the shared template — a running log of notable changes, seeded with an `[Unreleased]` section
+12. Applies the chosen visibility mode via `scripts/apply-project-visibility.sh`, which records it as `project_files_visibility` in `jenga.config.json` and performs any `.gitignore` change
+13. Stages and commits all files with the message `init: scaffold project structure and workflow config`
+
+The visibility mode is validated before any scaffolding happens, so an invalid
+value fails fast and leaves nothing behind. It is applied before the commit, so
+the `.gitignore` entry is captured in the initial commit.
+
+If the script fails, check that you are in the project root and that git and `jq`
+are available.
+
+See `skills/distribute/CONFIG_SCHEMA.md` for the full `project_files_visibility`
+field reference.
+
+### 4. Prompt next step
+
+Inform the user that setup is complete, and state which visibility mode was applied
+and where the working files now live. Mention that `docs/STRATEGY.md` was created as
+a strategic brief stub for investors, partners, and the product team — they can fill
+it in now or return to it later. Suggest running `/pi-plan` to define project goals
+and epics.

package/skills/j-init/assets/.gitignore_template

@@ -0,0 +1,15 @@
+# macOS & Windows system files
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Environment files
+.env
+.env.*
+*.local
+
+# Dependency directories
+node_modules/
+vendor/
+.venv/
+EOF

package/skills/j-init/assets/PROJECT_SUMMARY_template.md

@@ -0,0 +1,13 @@
+# Project Summary
+
+## Overview
+_To be completed._
+
+## Architecture & Structure
+_To be completed._
+
+## Epics
+_To be completed via /pi-plan._
+
+## Conventions
+_To be completed._

package/skills/j-init/assets/directory_structure.txt

@@ -0,0 +1,14 @@
+project/board/epics
+project/board/stories
+project/board/tasks
+project/instructions
+project/configs
+project/data
+project/queue
+project/rapports/problems
+project/rapports/analysis
+project/logs
+project/documentation
+project/documentation/plans
+project/documentation/summaries
+project/documentation/examples

package/skills/j-init/assets/scope-thresholds_template.json

@@ -0,0 +1,7 @@
+{
+  "threshold_version": 2,
+  "inline_max_files": 3,
+  "inline_max_lines": 75,
+  "story_max_files": 5,
+  "bundle_lock_ttl_minutes": 30
+}

package/skills/j-init/assets/strategy_stub_template.md

@@ -0,0 +1,38 @@
+# Strategy
+
+<!-- This document is intended for investors, strategic partners, and senior stakeholders.
+     Write in clear, confident language that conveys conviction and focus.
+     Avoid jargon. Prioritise substance over length. -->
+
+## Vision
+
+<!-- Describe the long-term direction of this project over a 3–5 year horizon.
+     What change do you want to see in the world, and what role does this project play in bringing it about?
+     A strong vision statement is specific, ambitious, and grounded — it should be possible to hold yourself accountable to it. -->
+
+## Value Proposition
+
+<!-- Articulate what makes this project uniquely valuable and to whom.
+     Answer: Why does this exist? Why now? Why this team?
+     Focus on the distinct advantage or insight that underpins the project — not features, but the underlying value delivered. -->
+
+## Scope
+
+### In Scope
+
+<!-- List the capabilities, domains, or problem spaces this project actively addresses.
+     Be specific enough that a new stakeholder can quickly understand the boundaries of the work.
+     Use bullet points for readability. -->
+
+### Out of Scope
+
+<!-- List what this project explicitly does not cover.
+     Revenue model, pricing strategy, and competitive analysis are intentionally excluded from this document —
+     they belong in separate artefacts and are out of scope here.
+     Use this section to prevent scope creep and set clear expectations with stakeholders. -->
+
+## Target Audience
+
+<!-- Describe who this project is built for.
+     Include both the end users (who experiences the product) and the stakeholders (who evaluates or funds it).
+     Be specific: a well-defined audience sharpens every other section of this document. -->

package/skills/j-init/assets/test-config_template.json

@@ -0,0 +1,4 @@
+{
+  "_note": "Run the tester agent to configure tools for this project.",
+  "tools": []
+}

package/skills/j-init/assets/workflow_template.json

@@ -0,0 +1,30 @@
+{
+  "statuses": ["Pending", "In Progress", "Passed", "Passed with remarks", "Failed", "Rejected", "Blocked"],
+  "rapport_types": ["conflict", "implementation_blocker", "security_concern", "test_failure", "analysis"],
+  "paths": {
+    "board": "project/board",
+    "epics": "project/board/epics",
+    "stories": "project/board/stories",
+    "tasks": "project/board/tasks",
+    "rapports_problems": "project/rapports/problems",
+    "rapports_analysis": "project/rapports/analysis",
+    "queue": "project/queue",
+    "scrum_triggers": "project/queue/scrum_triggers.jsonl",
+    "developer_triggers": "project/queue/developer_triggers.jsonl",
+    "tester_triggers": "project/queue/tester_triggers.jsonl",
+    "session_handoff": "project/queue/handoffs/",
+    "logs": "project/logs",
+    "data": "project/data",
+    "configs": "project/configs",
+    "documentation": "project/documentation",
+    "documentation_plans": "project/documentation/plans",
+    "documentation_summaries": "project/documentation/summaries"
+  },
+  "agents": ["developer", "tester", "scrum-master"],
+  "pipeline": [
+    {"step": 1, "agent": "scrum-master", "phase": "planning",        "on_complete": "write planning_complete handoff → developer_triggers.jsonl"},
+    {"step": 2, "agent": "developer",    "phase": "implementation",  "on_complete": "write implementation_complete handoff → tester_triggers.jsonl"},
+    {"step": 3, "agent": "tester",       "phase": "verification",    "on_complete": "write test status handoff → scrum_triggers.jsonl (+ developer_triggers.jsonl if failed)"},
+    {"step": 4, "agent": "scrum-master", "phase": "rollup_review",   "on_complete": "update board statuses, close epic/story if all done"}
+  ]
+}

package/skills/j-init/scripts/apply-project-visibility.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+#
+# apply-project-visibility.sh — apply the `project_files_visibility` mode to a project.
+#
+# Usage:
+#   apply-project-visibility.sh <mode> [project_root]
+#   apply-project-visibility.sh --check-only <mode>
+#
+# Modes:
+#   visible   Working files stay where they are. No-op on disk beyond the config write.
+#   ignored   Working files are added to the project's .gitignore — present on disk,
+#             never committed.
+#
+# NOTE: A third mode, `hidden` (dot-prefixing project/ -> .project/), was
+# implemented and then withdrawn before release. Testing found it functionally
+# broken: scripts/board_resolver.sh hardcodes project/configs/workflow.json
+# and never locates the rewritten path, and hooks/on_session_end.sh
+# unconditionally recreates a shadow project/ tree on every session end,
+# splitting runtime state across two trees. See
+# project/rapports/problems/E31_S05_T01-hidden-mode-path-resolution-gaps.md
+# for the full findings. Re-introducing `hidden` requires fixing both of
+# those hardcoded paths first — tracked as a follow-up /todo item.
+#
+# Exit codes:
+#   0  Success
+#   1  Bad usage or missing prerequisite
+#   2  Invalid mode (outside the two-value enum)
+#   3  Filesystem apply failure
+#   4  jenga.config.json write failure
+
+# Do NOT use set -e globally — each step handles its own errors.
+set -uo pipefail
+
+info() { echo "[visibility] $*"; }
+warn() { echo "[visibility] WARNING: $*"; }
+err()  { echo "[visibility] ERROR: $*" >&2; }
+
+usage() {
+  echo "Usage: $(basename "$0") <visible|ignored> [project_root]" >&2
+  echo "       $(basename "$0") --check-only <visible|ignored>" >&2
+  exit 1
+}
+
+# Every Jenga AI working file named in E31_S05 — the scrum board, todo.md,
+# queue/, rapports/ and logs/ — nests under this single root, so one entry
+# covers them all. `ignored` consumes this list.
+JENGA_WORKING_PATHS=("project")
+
+VALID_MODES="visible ignored"
+
+validate_mode() {
+  local mode="$1"
+  for valid in $VALID_MODES; do
+    [ "$mode" = "$valid" ] && return 0
+  done
+  err "Invalid project_files_visibility value: '${mode}'"
+  err "Allowed values are: ${VALID_MODES// /, }"
+  exit 2
+}
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+CHECK_ONLY=0
+if [ "${1:-}" = "--check-only" ]; then
+  CHECK_ONLY=1
+  shift
+fi
+
+MODE="${1:-}"
+[ -n "$MODE" ] || usage
+
+validate_mode "$MODE"
+
+if [ "$CHECK_ONLY" -eq 1 ]; then
+  info "Mode '$MODE' is valid."
+  exit 0
+fi
+
+PROJECT_ROOT="${2:-$PWD}"
+if [ ! -d "$PROJECT_ROOT" ]; then
+  err "Project root does not exist: $PROJECT_ROOT"
+  exit 1
+fi
+cd "$PROJECT_ROOT" || { err "Cannot enter project root: $PROJECT_ROOT"; exit 1; }
+
+if ! command -v jq >/dev/null 2>&1; then
+  err "jq is required to write jenga.config.json but was not found on PATH."
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# ignored — append to .gitignore, without ever duplicating an entry
+# ---------------------------------------------------------------------------
+
+gitignore_append() {
+  local entry="$1"
+  local gitignore=".gitignore"
+
+  if [ -f "$gitignore" ] && grep -qxF -- "$entry" "$gitignore"; then
+    info "'$entry' already present in .gitignore — skipping."
+    return 0
+  fi
+
+  # Don't glue our entry onto a final line that lacks a newline.
+  if [ -s "$gitignore" ] && [ -n "$(tail -c 1 "$gitignore")" ]; then
+    printf '\n' >> "$gitignore"
+  fi
+
+  if ! printf '%s\n' "$entry" >> "$gitignore"; then
+    err "Failed to append '$entry' to .gitignore"
+    exit 3
+  fi
+  info "Added '$entry' to .gitignore"
+}
+
+# ---------------------------------------------------------------------------
+# jenga.config.json — merge the field in, written atomically (temp + mv)
+# ---------------------------------------------------------------------------
+
+write_visibility_config() {
+  local mode="$1"
+  local config="jenga.config.json"
+  local tmp="${config}.tmp"
+  local existing='{}'
+
+  # /init normally runs before any /distribute, so the file usually does not
+  # exist yet. Merge rather than overwrite so other fields survive.
+  if [ -f "$config" ]; then
+    if ! jq empty "$config" 2>/dev/null; then
+      err "$config exists but contains malformed JSON — refusing to overwrite it."
+      exit 4
+    fi
+    existing="$(cat "$config")"
+  fi
+
+  local content
+  content="$(jq --arg v "$mode" '.project_files_visibility = $v' <<< "$existing")"
+  if [ -z "$content" ]; then
+    err "Failed to construct $config content."
+    exit 4
+  fi
+
+  if ! printf '%s\n' "$content" > "$tmp"; then
+    err "Failed to write temporary config file: $tmp"
+    exit 4
+  fi
+
+  if ! mv "$tmp" "$config"; then
+    err "Failed to atomically move $tmp to $config"
+    rm -f "$tmp"
+    exit 4
+  fi
+
+  info "Wrote project_files_visibility = \"$mode\" to $config"
+}
+
+# ---------------------------------------------------------------------------
+# Apply
+# ---------------------------------------------------------------------------
+
+case "$MODE" in
+  visible)
+    info "Mode 'visible' — working files stay in place; nothing to change on disk."
+    ;;
+  ignored)
+    for path in "${JENGA_WORKING_PATHS[@]}"; do
+      gitignore_append "${path}/"
+    done
+    ;;
+esac
+
+write_visibility_config "$MODE"
+
+info "Applied project_files_visibility '$MODE' to $PROJECT_ROOT"

package/skills/j-init/scripts/detect-existing-codebase.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/init/scripts/detect-existing-codebase.sh
+#
+# Deterministic front half of the /init "detect existing project state" step.
+# /init currently always scaffolds as though the target directory were empty.
+# That is wrong whenever a directory already carries a Jenga scaffold, or
+# already carries substantial application code that predates Jenga entirely
+# -- in the second case, scaffolding fresh produces an empty board and a stub
+# PROJECT_SUMMARY.md that actively misrepresent the project.
+#
+# This script answers exactly one question -- "what kind of directory is
+# this?" -- and nothing else. It never scaffolds, never prompts, never runs
+# /uncharted, and never modifies anything on disk. Deciding what to DO with
+# the verdict is agent judgement and lives in skills/init/SKILL.md.
+#
+# ---------------------------------------------------------------------------
+# VERDICTS -- exactly one is printed on stdout, nothing else
+# ---------------------------------------------------------------------------
+#   empty               The target is empty, or contains only boilerplate
+#                       that does not count as "there is a project here":
+#                       .git (the directory itself, pruned entirely -- not
+#                       merely excluded by name), .gitignore, and top-level
+#                       README*/LICENSE*/LICENCE* files (case-insensitive),
+#                       plus anything git itself reports as ignored. A repo
+#                       containing only a README is empty for this purpose.
+#   already-scaffolded  The target already carries a Jenga scaffold: any one
+#                       of project/board/, project/PROJECT_SUMMARY.md, or
+#                       project/configs/workflow.json is present. Checked
+#                       BEFORE the emptiness scan, so a scaffolded project
+#                       that also happens to look sparse is never misreported
+#                       as "empty".
+#   existing-codebase   The target has real content (source files, configs,
+#                       docs beyond the boilerplate list above, etc.) and is
+#                       not already Jenga-scaffolded. This is the case /init
+#                       currently mishandles: scaffolding fresh here silently
+#                       discards the fact that pre-existing code exists.
+#
+# ---------------------------------------------------------------------------
+# NOTES ON GITIGNORE HANDLING
+# ---------------------------------------------------------------------------
+# /init runs this check BEFORE `git init` in the fresh-scaffold path, so the
+# target directory is very often not a git work tree yet. Gitignore-based
+# filtering is therefore best-effort: it only runs when the target already
+# has a `.git` directory AND `git` is on PATH. A standalone `.gitignore` file
+# with no repository behind it still counts as boilerplate via the name-based
+# exclusion below -- it just cannot hide any OTHER file, because there is no
+# git to ask "is this ignored".
+#
+# README/LICENSE exclusion applies to TOP-LEVEL entries only. A directory
+# whose only content is a buried `docs/README.md` two levels down is real
+# structure, not boilerplate, and must not be reported as empty.
+#
+# ---------------------------------------------------------------------------
+# Usage
+# ---------------------------------------------------------------------------
+#   detect-existing-codebase.sh [target-dir]
+#
+#   target-dir   Directory to classify. Default: current directory.
+#
+# Options:
+#   -h, --help   Show this help and exit 0.
+#
+# Exit codes:
+#   0   A verdict was printed on stdout.
+#   1   Usage error (unknown option, more than one positional argument).
+#   2   target-dir does not exist or is not a directory.
+#
+# Requires: bash, find. git is used opportunistically for gitignore
+# filtering when the target is already a git work tree; its absence never
+# causes a failure.
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SELF="$(basename "$0")"
+
+usage() {
+  sed -n '/^# Usage$/,/^# Requires:/p' "$0" | sed -e 's/^# \{0,1\}//' -e '/^-\{10,\}$/d'
+}
+
+die_usage() {
+  printf '%s: error: %s\n' "$SELF" "$*" >&2
+  echo >&2
+  usage >&2
+  exit 1
+}
+
+TARGET_DIR="."
+HAVE_TARGET=0
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --)
+      shift
+      [ "$#" -le 1 ] || die_usage "at most one target directory is allowed"
+      if [ "$#" -eq 1 ]; then TARGET_DIR="$1"; HAVE_TARGET=1; fi
+      shift $#
+      ;;
+    -*)
+      die_usage "unknown option \"$1\"" ;;
+    *)
+      [ "$HAVE_TARGET" -eq 0 ] || die_usage "at most one target directory is allowed (got \"$TARGET_DIR\" and \"$1\")"
+      TARGET_DIR="$1"; HAVE_TARGET=1; shift ;;
+  esac
+done
+
+[ -d "$TARGET_DIR" ] || { printf '%s: error: not a directory: %s\n' "$SELF" "$TARGET_DIR" >&2; exit 2; }
+
+TARGET_DIR="$(cd -- "$TARGET_DIR" && pwd -P)"
+
+# --- already-scaffolded: checked first, independent of emptiness -----------
+if [ -d "$TARGET_DIR/project/board" ] \
+   || [ -f "$TARGET_DIR/project/PROJECT_SUMMARY.md" ] \
+   || [ -f "$TARGET_DIR/project/configs/workflow.json" ]; then
+  echo "already-scaffolded"
+  exit 0
+fi
+
+# --- enumerate candidate files, pruning .git entirely -----------------------
+ALL_FILES=$(mktemp "${TMPDIR:-/tmp}/detect-existing-codebase.XXXXXX")
+IGNORED_FILES=$(mktemp "${TMPDIR:-/tmp}/detect-existing-codebase-ignored.XXXXXX")
+cleanup() { rm -f "$ALL_FILES" "$IGNORED_FILES"; }
+trap cleanup EXIT
+
+find "$TARGET_DIR" -path "$TARGET_DIR/.git" -prune -o -type f -print > "$ALL_FILES"
+
+# --- best-effort gitignore filtering ----------------------------------------
+: > "$IGNORED_FILES"
+if [ -d "$TARGET_DIR/.git" ] && command -v git >/dev/null 2>&1; then
+  git -C "$TARGET_DIR" check-ignore --stdin < "$ALL_FILES" > "$IGNORED_FILES" 2>/dev/null || true
+fi
+
+# --- classify each candidate -------------------------------------------------
+SOURCE_FOUND=0
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+
+  if [ -s "$IGNORED_FILES" ] && grep -Fxq -- "$f" "$IGNORED_FILES"; then
+    continue
+  fi
+
+  rel="${f#"$TARGET_DIR"/}"
+  base="$(basename -- "$f")"
+  dir_rel="$(dirname -- "$rel")"
+
+  if [ "$dir_rel" = "." ]; then
+    if [ "$base" = ".gitignore" ]; then
+      continue
+    fi
+    base_upper="$(printf '%s' "$base" | tr '[:lower:]' '[:upper:]')"
+    case "$base_upper" in
+      README*|LICENSE*|LICENCE*) continue ;;
+    esac
+  fi
+
+  SOURCE_FOUND=1
+  break
+done < "$ALL_FILES"
+
+if [ "$SOURCE_FOUND" -eq 1 ]; then
+  echo "existing-codebase"
+else
+  echo "empty"
+fi