J-Init — Project Setup (polyfill alias of Init)

skills/j-init/ is the sole canonical directory for this skill. The j- prefix is there for collision safety: some host tools/harnesses (e.g. GH Copilot) ship their own built-in command literally named /init, which would shadow a bare /init alias, since Claude Code's native skill resolution is a literal-string, directory-name-based match — see project/documentation/skill-authoring.md's "Invocation Convention". Invoke it as j.init or /j-init.

This file was previously described as a duplicate of skills/init/, with an instruction to keep the two in lockstep. That instruction is void. E50_S15_T04 deleted every bare-name skills/<name>/ directory on 2026-09-19, making skills/j-<name>/ the sole canonical form (see project/documentation/skill-authoring.md's "The Canonical Naming Contract"), and scripts/generate-j-alias.sh — which had excluded this hand-maintained pair from generation anyway — was retired by E50_S14_T01. There is no second copy to mirror a change into, and none should be created. Edit this file directly.

Corrected by E42_S07_T01's follow-up, per project/rapports/problems/E42_S07_T01-j-init-skill-md-lockstep-instruction-still-stale.md. The same correction already landed one level down, in skills/j-init/scripts/apply-scaffold-visibility.sh.

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:

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

It prints exactly one verdict on stdout:

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/j-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 4. Do not apply it yourself — the script owns all of the mechanical work.

3. Ask whether the distributed scaffold should be committed

This is a distinct question from step 2 — project_files_visibility (step 2) covers only the project/ working tree (the scrum board, todo.md, queue/, rapports/, logs/). It has no effect on .claude//.agents/, the distributed framework scaffold (skill and agent definitions), which is a separate tree with a separate lifecycle — it gets overwritten wholesale by every /distribute run or npm upgrade, unlike project/. Kept as its own flag (scaffold_visibility) rather than folded into project_files_visibility's enum; see skills/j-distribute/CONFIG_SCHEMA.md's "Scaffold visibility" section for the full rationale.

Ask the user this question, verbatim, before running any script:

Should the distributed .claude/.agents Jenga AI framework scaffold (skills, agent
definitions — implementation detail, not your own code) be committed into this
project's git history?
1. Yes, commit it — keep it tracked and visible, exactly like today
2. No, keep it on disk but add it to .gitignore so it's 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 maps to one of visible (option 1) or ignored (option 2).

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 reproduces exactly today's behavior — the scaffold is still committed by default.

Carry the chosen value into step 4 as well. Do not apply it yourself — the script owns all of the mechanical work.

4. 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 choices from steps 2 and 3:

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> --scaffold-visibility <visible|ignored>

Omitting --visibility falls back to the JENGA_PROJECT_FILES_VISIBILITY environment variable, then to visible. Omitting --scaffold-visibility falls back to the JENGA_SCAFFOLD_VISIBILITY environment variable, then to visible — the same default-preserving fallback chain, applied independently to the distributed-scaffold question from step 3.

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 (empty tools; run the tester agent to configure test tools)
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 project/knowledge-graph/STUB_SCHEMA.md from the shared template and project/knowledge-graph/graph.json seeded with empty nodes/edges arrays — consumed by /uncharted's conversational elicitation flow
11. Creates the strategy brief stub (project/documentation/STRATEGY.md by default; the path comes from paths.strategy in workflow.json via scripts/strategy_path_resolver.sh, the same resolver /strategy uses) — intended for investors, partners, and the product team. It is an ordinary project/documentation/ file, so /init creates no docs/ directory; under project_files_visibility: ignored it is ignored with the rest of project/ (a project that wants it committed keeps visible or points paths.strategy elsewhere). A consumer project that already has a docs/STRATEGY.md is still found and updated in place by the resolver's legacy fallback; nothing is migrated automatically (E34_S07)
12. Creates CHANGELOG.md from the shared template — a running log of notable changes, seeded with an [Unreleased] section
13. 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
14. Applies the chosen scaffold visibility mode via scripts/apply-scaffold-visibility.sh, which records it as scaffold_visibility in jenga.config.json and, when ignored, adds .claude/ and .agents/ to .gitignore
15. Stages and commits all files with the message init: scaffold project structure and workflow config

Both visibility modes are validated before any scaffolding happens, so an invalid value fails fast and leaves nothing behind. Both are applied before the commit, so any resulting .gitignore entries are captured in the initial commit — this is what lets scaffold_visibility: ignored keep .claude//.agents/ out of the commit even though they may already exist on disk (from npm postinstall or a prior /distribute run) by the time /init runs git add -A.

If the script fails, check that you are in the project root and that git and jq are available.

See skills/j-distribute/CONFIG_SCHEMA.md for the full project_files_visibility and scaffold_visibility field reference.

5. Prompt next step

Inform the user that setup is complete, and state which visibility mode was applied for both project_files_visibility and scaffold_visibility, and where the working files and scaffold now live. Mention that the strategy brief (project/documentation/STRATEGY.md unless paths.strategy says otherwise) 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.

As the very last line, after that next-step prompt, run bash "$([ -f scripts/conventions-suggest.sh ] && echo scripts/conventions-suggest.sh || echo node_modules/@jenga-ai/agent/scripts/conventions-suggest.sh)" and print its output, if any (a one-line tip to run j.conventions; it prints nothing when the project already has a conventions.json). This is a non-blocking suggestion, not a question: do not wait for an answer, do not offer a menu for it, and do not run j.conventions on the user's behalf. The script always exits 0 and its output or absence never changes this skill's flow or exit status. If it cannot be run or prints nothing, say nothing and finish.