Workflow Rules

⚠️ CRITICAL — Source of Truth for All Features

All features — skills, agents, hooks, scripts, and any other implementation — MUST be created and edited in the root directories (skills/, agents/, hooks/, scripts/, etc.).

The .agents/ and .claude/ directories are generated build outputs. They are populated automatically by the j.distribute skill and must never be used as the primary location for new or updated features. Any change made only inside .agents/ or .claude/ will be overwritten on the next distribution run.

Rule: If you add or modify a skill, agent, hook, or script, the canonical file lives in the root directory. .agents/ and .claude/ are read-only artifacts.

Workflow Lifecycle

Invocation convention (E50_S01, separator revised by E50_S07, bare-form policy reversed by the E50 reopening of 2026-09-09): skills/j-<name>/ is the sole canonical form of a skill directory, and name: j.<name> (e.g. j.init, j.commit) is its canonical frontmatter identifier. Those are two separable identifiers, and only the directory changed: a skill is invoked as j.<name> — the form these docs have always taught, which survives untouched — or as the directory-resolved slash form /j-<name>.

The old bare /<name> form is hard-broken: no redirect, no alias, no deprecation shim, no warning. Its directory is deleted, and since Claude Code resolves skills by literal directory name, the command simply stops resolving — no Jenga skill runs and nothing points the user at /j-<name>. The earlier policy, which guaranteed the bare form would keep resolving indefinitely on every routing surface, was reversed on 2026-09-09 and is retained in project/documentation/skill-authoring.md only as superseded history.

Four permanent exceptions keep their bare directory names and are never renamed, deleted, or twinned: skills/jenga/, skills/jenga-permission-level/ and skills/jenga-config/ (main skills, deliberately excluded from twin generation; E50_S06 for the first two, E68_S04 for the third) and skills/index/ (not a skill — no SKILL.md, not part of routing). Consequently /jenga, /jenga-permission-level and /jenga-config do keep working — they are the only surviving bare slash forms, and they survive because those directories were always the canonical ones, not because any alias was kept.

Full contract in project/documentation/skill-authoring.md's "The Canonical Naming Contract" section; the mechanical cutover (directory renames, frontmatter rewrites, reference updates) is owned by E50_S11–E50_S18.

1. j.init — Scaffold the project: git init, directories, workflow.json, PROJECT_SUMMARY.md stub.
2. j.jenga — Interactive-by-default board orchestrator: bare shows a picker + confirmation tree, <ids> scopes and confirms, * runs the original fully automated pipeline with no prompts.
3. j.todo (or Scrum Master directly) — Translate requirements into board items (epics → stories → tasks).
4. j.do — Pick a task from project/todo.md, invoke the Developer agent with full scrum board context and a sender object.
5. Developer — Reads task, creates a worktree, implements, commits, and calls the Tester.
6. Tester — Validates sender object, runs tests, writes status to the board, triggers rollup if all tasks pass.
7. SessionEnd hook — on_session_end.sh detects new rapports and writes triggers to the queue.
8. Scrum Master (next session) — Processes the queue: rapport review, status review, story/epic rollup.

Agents

Scrum Master (agents/scrum-master.md)

• Owns project/PROJECT_SUMMARY.md — sole writer.
• Processes project/queue/scrum_triggers.jsonl at every session start.
• Creates and amends epics, stories, and tasks using the scrum board schema.
• Handles story and epic rollup when all child items pass.
• Applies advisory file locks before writing any board file.

Developer (agents/developer.md)

• Creates an isolated git worktree per task (<E##_S##_T##-slug>).
• Logs all incoming sender objects to project/logs/events.json before doing any work.
• Commits at meaningful milestones (not every line, not only at the end).
• Calls the Tester with a full sender object including commit SHAs.
• Never runs tests — that is the Tester's exclusive responsibility.
• After three failed conflict resolutions, writes a rapport, sets status to Blocked, and halts.
• Never commits .env files or credentials.

Tester (agents/tester.md)

• Sole agent permitted to write the judged task and story statuses on the board. The five lifecycle statuses (Merged, Publicized, Privatized, Deployed to Stage, Deployed to Prod) are script-set and are the exception; the rule, including what to do about an unexpected script-set write, lives in templates/SCRUM_BOARD_SCHEMA.md (Status Values, "Status Writers").
• Validates all required sender fields before proceeding (rejects with "error" if any are missing).
• Manages the full testing lifecycle: unit, integration, e2e, SAST, vulnerability, performance, coverage.
• Test tool configuration lives in project/configs/test-config.json (user-approved).
• Before a task, story or epic closes, runs the configured scope test policy (test_run_task / test_run_story / test_run_epic in project/configs/test-config.json; defaults none, scoped, full) via skills/j-test/scripts/scope-test-gate.sh; see project/documentation/test-runner.md.
• SAST/vulnerability scans are opt-in and require explicit user approval, logged to events.json.
• Writes Rejected status only after notifying the user and receiving confirmation.
• After every status update, checks for story/epic rollup and writes a trigger to the queue if warranted.
• Maintains analytics baselines in project/data/baselines.json across sessions.

Skills (Slash Commands)

Skills are stored in skills/j-<name>/SKILL.md. Invoke them with j.<name> in a Claude Code session, or as the directory-resolved slash form /j-<name>. The bare /<name> form does not resolve (see the Invocation Convention note under Workflow Lifecycle above).

✅ Cutover landed. The bare-name directories have been deleted and the j.j-<name> → j.<name> frontmatter rewrite has landed, both in the single E50_S15_T04 commit. This block and the Invocation Convention note above now describe the actual current directory listing — only skills/j-<name>/ directories (plus the four permanent exceptions) remain under skills/. Provenance: E50_S15_T04 (deletion + rewrite), verified end-to-end by E50_S15_T05 (full test suite, allow-list/mirror resync, doc cleanup).

skills/j-<name>/ is the canonical skill directory (E50_S05, promoted from twin to sole canonical form by the E50 reopening of 2026-09-09): it is the hand-edited source of truth — the directory you create, edit, and commit — not a generated duplicate of a bare-name directory. Now that E50_S15 has landed, no bare-name directory remains to generate it from or keep it in lockstep with. Its j- prefix exists for collision safety: a real directory under a distinct name, rather than a routing/frontmatter alias, for cases where a host tool ships its own same-named built-in command (e.g. GitHub Copilot's own /init, which motivated j-init in the first place) and would otherwise shadow a bare /<name> form. Note the directory name (j-<name>) and the frontmatter name: (j.<name>) are deliberately different — see the Skill Frontmatter table below.

skills/jenga/, skills/jenga-permission-level/, skills/jenga-config/, and skills/index/ are the four permanent exceptions that keep their bare directory names (see the Invocation Convention note above). skills/init/ is not an exception — skills/j-init/ is simply already at its canonical name.

scripts/generate-j-alias.sh's bare-name-source → j-<name>-twin generation relationship no longer applied once this contract landed, since both ends of it were invalidated by it — E50_S14 retired the script outright (deleted, not hardened) rather than inverting it. scripts/apply-j-prefix.sh was kept, fixed to accept the settled j-<name> directory / j.<name> frontmatter pairing instead of requiring exact string equality. Full contract, including both decisions and their reasoning, in project/documentation/skill-authoring.md's "The Canonical Naming Contract" section (see its "Generation" subsection).

jenga config — terminal command, not a skill

jenga config (lib/commands/config.js, behind the jenga bin) lists and edits the settings in project/configs/*.json (interactively, or with jenga config get|set <file-id>.<key>). It is deterministic and agentless: no model call, zero token cost, so it never appears in the skills table above and is not invoked as j.config. A successful set also increments the file's version counter (threshold_version, config_version). Usage, exit codes and the editable versus read-only split are in project/configs/README.md.

Skill Frontmatter

Each SKILL.md starts with a YAML frontmatter block. Supported fields:

---
name: j.<skill-name>
description: <one-sentence description>
metadata:
  prefered_agent: <agent_name>   # optional
keywords:                        # optional
  - "<short phrase>"
examples:                        # optional
  - "<natural-language prompt>"
---

See project/documentation/skill-authoring.md for the full authoring guide.

prefered_agent

When a SKILL.md file contains a prefered_agent property in its YAML frontmatter, it indicates which sub-agent should be used to execute the skill. When invoking the skill, delegate execution to that agent by loading its definition from agents/<agent_name>.md and passing it the skill's instructions along with all relevant context.

Valid values match the agent definitions in the agents/ directory: scrum-master, developer, tester.

Skills without this property are executed directly without delegating to a sub-agent.

Skill Implementation Principle — Scripts Over Inline Logic

When implementing or authoring a skill, offload deterministic, repeatable steps to shell scripts or other static tooling (e.g., bash scripts in skills/j-<name>/scripts/, shared scripts in scripts/) rather than encoding them as agent instructions inside SKILL.md.

Why:

• Scripts execute consistently regardless of model, context length, or session state
• Moving logic out of SKILL.md reduces token consumption on every invocation
• Scripts are version-controlled, testable, and reusable across skills

Apply this principle when a step:

• Runs a fixed sequence of shell commands (git operations, file manipulation, validation)
• Produces structured output that the agent then reads and acts on
• Would be identical across every invocation (no dynamic reasoning required)

Keep in SKILL.md what requires agent judgment: interpreting output, making decisions based on context, presenting results to the user, and handling edge cases that cannot be enumerated in advance.

Documentation Placement — docs/ versus project/documentation/ versus site/

Rule (E34_S06, revised by E70_S02): docs/ belongs to the project; Jenga scaffolds it but never puts Jenga content in it; Jenga's internal documents live in project/documentation/, the published site source lives in site/. Maintainer-internal documentation — design notes, mirror and distribution rules, protocol and parity docs, decision records, execution plans and summaries — lives under project/documentation/, the documentation path in project/configs/workflow.json.

One-line test: would someone who only installed the package want to read this? If not, it is internal.

Skills and agents that create documentation resolve the destination from workflow.json's paths.documentation; they never default to docs/. The strategy brief is not an exception: it is an ordinary project/documentation/STRATEGY.md file (resolved via paths.strategy). The site's decision record is project/documentation/site-decisions.md.

Interaction Pattern

When presenting options to the user, ALWAYS use this format instead of open-ended questions if possible:

What would you like to do?
1. Option A
2. Option B  
3. Option C
4. Other (describe below)

Avoid ask open-ended questions where a list of options would serve better. Free-text input must always appear as the final numbered option.

MCP Tools

mcp/help

Discovers available skills by scanning .agents/skills/. help(path?) returns skill folder names.

cd mcp/help && npm install
node index.js

mcp/execute-ticket

Planned: creates a sub-agent, initialises a git worktree, and names the session after the task ID. See mcp/execute-ticket/index.js.

Hooks

Hooks are configured in settings.json and fire automatically during a Claude Code session.

hooks/on_session_end.sh

Runs at the end of every Developer or Tester session: logs a session-end event to events.json, compares rapports/problems/ against .rapport_manifest.json (skipping *.IGNORE.md files) and writes a rapport_review trigger if new rapports are found, then always appends a status_review trigger for the next Scrum Master session.

hooks/on_preflight_check.sh

The enforcing layer of the pre-flight checklist feature (E67_S04). Fires on PreToolUse for Bash, Task and Agent calls, reads the situation marker (scripts/checklist-marker.sh) to learn which lifecycle phase is active, runs scripts/checklist.sh check <phase> with the run id from the marker frame, and refuses the tool call when a block-enforcement item is unsatisfied. It exists so that enforcement does not ultimately depend on an agent choosing to call the checker.

• No marker, no effect. With no lifecycle phase active it exits 0 with no output and no subprocess — measured at 11.0 ms/call against a 9.9 ms bare-bash floor.
• It gates each phase's own irreversible operation, not every tool call (pre-commit → git commit, pre-task → subagent dispatch and git worktree add, pre-release/pre-publish → npm publish / gh release / git push / git tag, pre-mirror → git push / mirror.sh, pre-reconcile → git merge / git worktree remove). Gating everything would wedge the session, because satisfying a failed item is itself a tool call.
• It holds at every permission level, including 5 (Unrestricted). Its decision never consults permission state, and there is no environment variable that disables it.
• It is registered in six files, not one. scripts/jenga-permission-level-switch.sh whole-file-overwrites .claude/settings.json and .agents/settings.json from templates/permission-levels/level-<n>-<name>.json, so a hook present only in the root settings.json is silently dropped by any /jenga-permission-level switch — the same bug E15_S04_T01 fixed for the WorktreeCreate commit guard. The PreToolUse block is therefore byte-identical across the root settings.json and all five templates. Change all six together.

Full contract: the script's own header comment, and section 9 of project/documentation/preflight-checklists.md.

Subject Divergence Detection

What Counts as Divergence

A subject has diverged when the user introduces any of the following mid-session:

• A new feature request unrelated to the task or story currently in focus
• An unrelated suggestion (tooling change, refactor, workflow idea) that would require separate planning
• A scope-expanding idea that goes beyond the current story's Acceptance Criteria or Definition of Done

Clarifying questions, follow-up details, or edge cases that directly serve the current topic are not divergence.

Detection & Prompt

When divergence is detected, immediately pause the current line of work and present the following structured choice:

It looks like we're moving into a new topic. How would you like to handle it?
1. Capture the **new topic** as a `j.todo` (I'll return to what we were doing)
2. Capture the **current topic** as a `j.todo` (I'll continue with the new topic)
3. Capture **both** as `j.todo` items (you choose which to continue first)
4. Ignore it — tell me which topic to continue with

Option A — Capture the Diverging Topic

1. Summarise the diverging topic using context gathered so far and create a j.todo with that summary as the description.
2. Offer j.brainstorm to fill in any missing Prerequisites before finalising the j.todo.
3. Once the j.todo is saved, return to the primary topic exactly where it was paused.

Option B — Capture the Primary Topic

1. Summarise the primary topic using context gathered so far and create a j.todo with that summary as the description.
2. Offer j.brainstorm to fill in any missing Prerequisites before finalising the j.todo.
3. Once the j.todo is saved, continue with the diverging topic.

Option C — Capture Both

1. Create a j.todo for the diverging topic (with context summary and a j.brainstorm offer for Prerequisites).
2. Create a j.todo for the primary topic (with context summary and a j.brainstorm offer for Prerequisites).
3. Ask the user which topic to continue first.

Context Surfacing

In every j.todo description created through this flow, include:

• A one-sentence summary of the topic
• Key details, constraints, or decisions already discussed
• Any open questions or unknowns raised so far

This ensures no context is lost regardless of which option the user chooses.

Edge Cases

• User declines both options (selects "Ignore it"): Acknowledge the choice without creating any j.todo items, then ask the user to explicitly state which topic to continue. Follow their direction.
• User wants to pursue both in parallel: Treat this as Option C — capture both as j.todo items with full context summaries, then ask the user which to continue first.