@jenga-ai/agent 1.0.1 → 1.1.1

package/skills/init/SKILL.md

@@ -18,14 +18,93 @@ examples:
 
 Follow these steps in order. Do not skip steps — the sequence matters.
 
-### 1–9. Run the scaffold script
+### 1. Detect existing project state
 
-Execute the init script from the project root:
+Before asking anything or scaffolding anything, classify the target directory
+(the current directory) by running the detection script:
 
 ```bash
-chmod +x ./scripts/init.sh && ./scripts/init.sh
+skills/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 JengaAgent's working files should appear
+
+Ask the user this question, verbatim, before running any script:
+
+    How should JengaAgent'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
+
+Execute the init script from the project root, passing the choice from step 2:
+
+```bash
+chmod +x ./scripts/init.sh && ./scripts/init.sh --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`
@@ -35,10 +114,25 @@ This script handles all scaffolding in one step:
 6. Creates `project/configs/test-config.json` stub
 7. Creates `project/data/baselines.json`
 8. Creates `project/logs/events.json`
-9. Stages and commits all files with the message `init: scaffold project structure and workflow config`
+9. Creates `docs/STRATEGY.md` — a strategic brief stub intended for investors, partners, and the product team
+10. Creates `CHANGELOG.md` from the shared template — a running log of notable changes, seeded with an `[Unreleased]` section
+11. 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
+12. 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.
 
-If the script fails, check that you are in the project root and that git is available.
+See `skills/distribute/CONFIG_SCHEMA.md` for the full `project_files_visibility`
+field reference.
 
-### 10. Prompt next step
+### 4. Prompt next step
 
-Inform the user that setup is complete and suggest running `/pi-plan` to define project goals and epics.
+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/init/assets/directory_structure.txt

@@ -1,6 +1,7 @@
 project/board/epics
 project/board/stories
 project/board/tasks
+project/instructions
 project/configs
 project/data
 project/queue

package/skills/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/init/assets/workflow_template.json

@@ -12,7 +12,7 @@
     "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/.session_handoff.json",
+    "session_handoff": "project/queue/handoffs/",
     "logs": "project/logs",
     "data": "project/data",
     "configs": "project/configs",

package/skills/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 JengaAgent 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/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

package/skills/init/scripts/init.sh

@@ -3,6 +3,25 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ASSETS_DIR="$SCRIPT_DIR/../assets"
+VISIBILITY_SCRIPT="$SCRIPT_DIR/apply-project-visibility.sh"
+
+# ─── 0. Resolve project_files_visibility ─────────────────────────────────────
+# Defaults to `visible` — the only value that touches nothing on disk — so an
+# unattended run can never silently relocate directories or edit .gitignore.
+VISIBILITY="${JENGA_PROJECT_FILES_VISIBILITY:-visible}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --visibility)   VISIBILITY="${2:-}"; shift 2 ;;
+    --visibility=*) VISIBILITY="${1#*=}"; shift ;;
+    *) echo "Unknown argument: $1" >&2
+       echo "Usage: $(basename "$0") [--visibility <visible|ignored>]" >&2
+       exit 1 ;;
+  esac
+done
+
+# Validate before scaffolding so a typo cannot leave a half-initialised project.
+bash "$VISIBILITY_SCRIPT" --check-only "$VISIBILITY"
 
 # ─── 1. Initialize git repository ────────────────────────────────────────────
 echo "→ Initializing git repository..."
@@ -39,7 +58,22 @@ echo '{}' > project/data/baselines.json
 echo "→ Creating events.json..."
 echo '[]' > project/logs/events.json
 
-# ─── 9. Initial commit ───────────────────────────────────────────────────────
+# ─── 9. Create docs/STRATEGY.md ──────────────────────────────────────────────
+echo "→ Creating docs/STRATEGY.md (strategic brief for investors, partners, and the product team)..."
+mkdir -p docs
+cp "$ASSETS_DIR/strategy_stub_template.md" docs/STRATEGY.md
+
+# ─── 10. Create CHANGELOG.md ──────────────────────────────────────────────────
+echo "→ Creating CHANGELOG.md from template..."
+cp "$SCRIPT_DIR/../../../templates/CHANGELOG_TEMPLATE.md" CHANGELOG.md
+
+# ─── 11. Apply project_files_visibility ──────────────────────────────────────
+# Runs before the commit so the .gitignore entry (ignored) is captured in the
+# initial commit.
+echo "→ Applying project files visibility ($VISIBILITY)..."
+bash "$VISIBILITY_SCRIPT" "$VISIBILITY" "$PWD"
+
+# ─── 12. Initial commit ──────────────────────────────────────────────────────
 echo "→ Staging and committing scaffolded files..."
 git add -A
 git commit -m "init: scaffold project structure and workflow config"