@jenga-ai/agent 2.0.0 → 3.0.0

package/README.md

@@ -1,8 +1,7 @@
 # Jenga AI
+### No agent merges its own code.
 
-> ⚠️ **Upgrading from a prior version?** Earlier releases could hit a command-collision bug: some host tools (e.g. GitHub Copilot) ship their own built-in `/init` command, which could silently shadow Jenga's own `/init` skill. This release adds **`/j-init`** — an identical, collision-safe copy of `/init` — so you always have a guaranteed-unshadowed way to scaffold a project. If `/init` isn't behaving as documented, run `/j-init` instead.
-
-**A structured multi-agent development workflow that works with any AI agent or AI-native IDE.** Three specialised AI agents — Scrum Master, Developer, and Tester — collaborate through a shared scrum board, an event-driven trigger queue, and a coordinated pipeline of `j:`-prefixed skills that hand work between them — to take a project from idea to verified, committed code — across as many sessions as it takes.
+Jenga AI is an agentic software engineering framework for AI-assisted development: it splits work across three role-bounded agents — a Scrum Master that plans, a Developer that implements in an isolated git worktree, and a Tester that runs your test suite and owns the board status. Work survives session boundaries as Epics, Stories, and Tasks on a Markdown board your agent reads at the start of every session.
 
 [![npm version](https://img.shields.io/npm/v/@jenga-ai/agent.svg)](https://www.npmjs.com/package/@jenga-ai/agent)
 [![license](https://img.shields.io/npm/l/@jenga-ai/agent.svg)](LICENSE)
@@ -13,125 +12,107 @@ npm install @jenga-ai/agent
 
 ## The Problem It Solves
 
-Without a framework like Jenga AI, AI-assisted development has serious structural weaknesses:
+You've had this happen: Claude wrote the feature, said it worked, and the session ended. Next session it had no idea any of it existed. Without a framework like Jenga AI, AI-assisted development has serious structural weaknesses:
 
 [![How AI Coding Agents Understand Your Codebase & Developer Tools](https://img.youtube.com/vi/zAe-sau06io/maxresdefault.jpg)](https://www.youtube.com/watch?v=zAe-sau06io)
 
-*"How AI Coding Agents Understand Your Codebase & Developer Tools" — IBM Technology on the same gap in session memory and tooling context that Jenga AI's board and agent contracts are built to close.*
+*"How AI Coding Agents Understand Your Codebase & Developer Tools" — IBM Technology on the same gap in persistent development context and tooling context that Jenga AI's board and agent contracts are built to close.*
 
 | Problem | Reality |
 |---|---|
-| **AI has no session memory** | Every AI agent session starts from scratch — no awareness of open tasks, past decisions, or what was already tested |
+| **No persistent engineering context** | Every AI agent session starts from scratch — no awareness of open tasks, past decisions, or what was already tested |
 | **No role separation** | The AI writes *and* "tests" code in the same context, leading to hallucinated test results and self-affirming bugs |
 | **No structured planning** | Work happens ad-hoc — no Epic → Story → Task hierarchy to organise or track progress |
 | **No handoff protocol** | Switching from implementing to testing means manually re-explaining context every time |
 | **No audit trail** | You can't replay *why* something was built, by which agent, based on which task |
 | **Sessions just end** | Work-in-progress, unresolved problems, and incomplete stories silently vanish |
 
-Jenga AI solves each of these with structure: persistent board state, strict agent roles, typed inter-agent contracts, and session-end hooks that preserve context between sessions.
+Jenga AI solves each of these with structure: persistent engineering context maintained via board state, strict agent roles, typed inter-agent contracts, and session-end hooks that carry that context between sessions.
 
 ---
 
 ## What You Get
 
 - **Three specialised agents** — Scrum Master, Developer, Tester — each with a distinct role and no self-graded work
-- **A persistent scrum board** — Epics, Stories, and Tasks tracked as Markdown files with structured frontmatter, surviving every session boundary
-- **A coordinated skill pipeline, not a command list** — planning skills (`j:pi-plan`, `j:todo`) hand off to execution skills (`j:do`, `j:dooo`), which hand off to review skills (`j:status`, `j:reconcile`), each stage reading and writing the same board state — the old bare `/<name>` form still works everywhere as a permanent alias
+- **A persistent, Kanban-style scrum board** — Epics, Stories, and Tasks tracked as Markdown files with structured frontmatter, surviving every session boundary
+- **A coordinated skill pipeline — one agentic workflow, not a command list** — planning skills (`j.pi-plan`, `j.todo`) hand off to execution skills (`j.do`, `j.dooo`), which hand off to review skills (`j.status`, `j.reconcile`), each stage reading and writing the same board state — the old bare `/<name>` form still works everywhere as a permanent alias
 - **An event-driven trigger queue** — async handoffs between agents with a full audit trail in `project/logs/events.json`
 - **Isolated git worktrees per task** — the Developer never works directly on your main branch
-- **Works with any AI agent or IDE** — Claude Code, GitHub Copilot, and Codex CLI are all supported today
+- **Works with any AI coding agent or AI-native IDE** — Claude Code, GitHub Copilot, and Codex CLI are all supported today
 
 > 📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md) | [Intro Guide](project/.wiki/intro-guide.md)
 
+### "Isn't this just an LLM grading another LLM?"
+
+The Tester doesn't read your code and form an opinion about it. It executes the test suite you configure in `project/configs/test-config.json` and reports pass or fail — in this repo, `bats` for unit and integration, `shellcheck` for SAST. What Jenga guarantees structurally is that the agent that wrote the code is not the agent that decides it's done, and doesn't get to write its own status onto the board. What comes out of that gate depends on what you wire into it — the same as any CI pipeline.
+
 ## Platform Support
 
 | Agent | Skills & Agents | Root Context File |
 |---|---|---|
-| **Claude Code** | `.claude/` — mirrored automatically on install | `CLAUDE.md` — generated by `j:init` today |
+| **Claude Code** | `.claude/` — mirrored automatically on install | `CLAUDE.md` — generated by `j.init` today |
 | **GitHub Copilot** | `.agents/` — mirrored automatically on install | `.github/copilot-instructions.md` — bootstrapped at `npm install` time, refined by `jenga init` |
-| **Codex** | `.agents/` — mirrored automatically on install | `AGENTS.md` — generated by `j:init` today |
+| **Codex** | `.agents/` — mirrored automatically on install | `AGENTS.md` — generated by `j.init` today |
 
-`CLAUDE.md` and `AGENTS.md` are generated unconditionally by `j:init` — every agent gets a real, populated root-level context file out of the box, not just a pointer. If either file already exists as a genuine pre-existing user file, Jenga writes its own copy as `J-CLAUDE.md` / `J-AGENTS.md` instead and inserts a short reference into the existing file, leaving it otherwise untouched.
+`CLAUDE.md` and `AGENTS.md` are generated unconditionally by `j.init` — every agent gets a real, populated root-level context file, not just a pointer. If either file already exists as a genuine pre-existing user file, Jenga leaves it untouched, writes its own copy as `J-CLAUDE.md` / `J-AGENTS.md`, and inserts a short reference line into the original.
 
-`.github/copilot-instructions.md` follows a different path: `scripts/postinstall.js` writes it unconditionally and non-interactively the moment `npm install` finishes, so Copilot has working `j:<name>` routing instructions (the bare `/<name>` form also still resolves, as a permanent alias) even if a consumer's very first action is a Copilot slash command, before the separate `jenga init` CLI wizard has ever run. Running `jenga init` afterward refines the same file using the user's actual chosen skills path — it is never generated by the `j:init` skill itself.
+`.github/copilot-instructions.md` follows a different path, because Copilot needs it before `j.init` may ever run: `npm install` triggers `scripts/postinstall.js`, which writes it unconditionally and non-interactively, so `j.<name>` routing (the bare `/<name>` form still resolves too, as a permanent alias) works from a consumer's very first Copilot command. A later `jenga init` run refines that same file using the project's actual chosen skills path.
 
 ---
 
 ## Examples
 
-### Before / After
+### A Real Session, On This Repo
 
-**Without Jenga AI:**
-```
-You: "Add user authentication"
-AI agent: [writes auth code, declares it works, session ends]
+Not a demo — this is what actually produced the section you're reading.
 
-Next session:
-You: "What's the status of auth?"
-AI agent: "I don't have context from the previous session."
-```
+The conversation starts with a request to align this README's language and content with a positioning plan drafted for this epic (E41):
 
-**With Jenga AI:**
 ```
-j:todo → "Add user authentication" → linked to E01_S02
-j:do   → Developer creates worktree E01_S02_T01-auth
-       → implements, commits at milestones
-       → hands off to Tester with sender object
+j.improve E41: I want to make some adjustments to the README in both
+language as well as content to better match [the E41 positioning plan]
+[...]
+```
 
-Tester → runs tests, updates board status to ✅ Passed
-SessionEnd → writes status_review trigger to queue
+That plan already existed, so the copy gets edited directly — no need to re-run a fresh analysis pass just to re-derive it. A few edits later, ten more issues surface, one with an `j.brainstorm` request attached:
 
-Next session:
-j:status → "E01_S02 ✅ complete — E01_S03 pending"
+```
+Then do a j.todo on this, as there are more places that should be
+edited based on that scrutiny rapport:
+* Remove warning banner about Copilot conflict
+[...]
+* Fewer, better and more relatable examples, we should
+  j.brainstorm this so I can send examples from real world usecases
+[...]
+* Should we really display the entire Skill list here?
+[...]
 ```
 
----
-
-### Real-World Scenario: Building a Feature Across Sessions
+`j.todo` classifies the ten items into two stories: nine mechanical README fixes (`E41_S10`), and the Examples section you're reading right now (`E41_S11`) — carved out and held back specifically because of that `j.brainstorm` request, since a real example had to come from the user, not be invented.
 
-Imagine you're building a REST API with auth, rate limiting, and an admin dashboard. Each is a separate Epic. Here's how Jenga AI handles that across multiple days:
+Once `E41_S10` is on the board, it's picked to run first. The Scrum Master reads the story and decomposes it into seven tasks, executed through `j.do`. Five are small, single-file text fixes deemed `--trivial` — they run inline, smoke-tested and committed directly, no worktree needed. Two need an editorial call — one of them being which skills are "foundational" enough to stay inline — those escalate to a real git worktree with a Developer and a Tester. The Tester independently re-verifies the diff, catches one file the Developer missed, fixes it, and queues the story for rollup. The Scrum Master processes that queue next: `E41_S10` → `Passed`. Epic `E41` stays `In Progress` — three other stories are still open.
 
-**Planning**
-```
-j:init         → scaffolds project/, board/, workflow.json
-j:pi-plan      → Scrum Master helps shape the auth epic into stories
-j:todo         → "Add JWT auth" → E01_S01, "Add refresh tokens" → E01_S02
-```
+Then, circling back to the deferred request:
 
-**Implementation**
-```
-j:do           → Developer picks up E01_S01_T01-jwt-middleware
-               → creates isolated worktree, implements, commits
-               → Tester validates, marks Passed, triggers rollup
-j:status       → E01_S01 ✅, E01_S02 Pending
-j:continue     → picks up E01_S02 automatically
-j:proceed      → resumes project plan from current board state
 ```
+Jenga AI: [...] Remaining open thread from this session: E41_S11
+(Examples rework) is on the board but not started — it's gated on
+a j.brainstorm session where you supply real-world use cases. Want
+to do that now, or leave it queued?
 
-**New idea mid-session**
-```
-You: "Actually, let's also add API rate limiting while we're at it"
-j:btw          → captures "rate limiting" as E02 without losing E01 context
-               → returns focus to E01_S02
-j:spinoff      → captures a diverging topic mid-conversation, saves as j:todo
-               → returns focus to primary thread
+You: do it now
 ```
 
-**Parallel work**
-```
-j:jenga        → interactive board orchestrator: pick or scope, confirm, then execute (`j:jenga *` for the original fully automated, no-prompts run)
-j:dooo         → orchestrates E01_S02 and E02_S01 in parallel sub-agents
-j:reconcile    → syncs board with actual git history after parallel merges
-```
+`j.brainstorm` opens for the gated story — the session you're reading right now, working out what this example should even say.
 
-The board, the audit log, and `PROJECT_SUMMARY.md` survive every session boundary. You never re-explain context.
+Nobody hand-wrote this task breakdown. The board did it, the routing rules decided what needed a real worktree versus what could run inline, and the Tester — not the agent that made the edits — decided when each piece was actually done. The board entries are real: `E41_S10` and `E41_S11`.
 
 ---
 
-## How It Works
+## How Jenga AI's Agentic Workflow Works
 
 ```
-j:init → j:pi-plan → j:todo → j:do
+j.init → j.pi-plan → j.todo → j.do
                               │
                      Developer agent
                      (isolated worktree, commits)
@@ -172,7 +153,7 @@ Each agent is defined in `.agents/agents/`. They communicate exclusively through
 
 **Prerequisites:** An AI agent or AI-native IDE. Supported platforms include:
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-- GitHub Copilot (VS Code extension or CLI)
+- [GitHub Copilot](https://github.com/features/copilot) (VS Code extension or CLI)
 - Codex CLI
 
 **Install from npm:**
@@ -182,13 +163,13 @@ npm install -g @jenga-ai/agent
 
 Or clone directly:
 
-1. **Clone or copy this repo** into your project's `.agents/` directory (or wherever you keep project tooling).
-2. **Run `j:init`** — scaffolds `project/`, creates `workflow.json`, `PROJECT_SUMMARY.md`, and makes an initial commit.
-3. **Run `j:pi-plan`** — define your project goals and initial epics.
-4. **Run `j:todo`** — describe features to implement; they're linked to the board automatically.
-5. **Run `j:do`** — picks the first task and drives the full implement → test → commit loop.
+1. **Clone or copy this repo** into your project's root.
+2. **Run `j.init`** — scaffolds `project/`, creates `workflow.json`, `PROJECT_SUMMARY.md`, and makes an initial commit.
+3. **Run `j.pi-plan`** — define your project goals and initial epics.
+4. **Run `j.todo`** — describe features to implement; they're linked to the board automatically.
+5. **Run `j.do`** — picks the first task and drives the full implement → test → commit loop.
 
-Run `j:status` at any time to see where the project stands.
+Run `j.status` at any time to see where the project stands.
 
 ---
 
@@ -208,189 +189,40 @@ The framework is platform-agnostic by design — any AI agent that can read Mark
 
 ## Skills (Slash Commands)
 
-Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `j:<name>` in your AI agent or IDE's command interface — the old bare `/<name>` form also keeps working permanently as an alias.
-
-### Setup & Planning
-
-| Command | Description |
-|---|---|
-| `j:init` | Scaffold project directories, `workflow.json`, `PROJECT_SUMMARY.md`, initial git commit |
-| `j:jbp` | Scaffold using the [JengaBasePlate](https://github.com/samwelmunga/JengaBasePlate.git) boilerplate |
-| `j:jenga` | Interactive-by-default board orchestrator — bare shows a picker + confirmation tree, `<ids>` scopes and confirms, `*` runs fully automated with no prompts |
-| `j:pi-plan` | Define or expand Epics in `PROJECT_SUMMARY.md` — use at start or when adding major new work |
-| `j:brainstorm` | Focused planning session with the Scrum Master before committing anything to the board |
-| `j:deep-dive` | Multi-phase investigation — gathers info, brainstorms, scrutinises, and produces a refined output |
-| `j:uncharted` | Entry point for code with no board provenance — `segment` (a file or directory), `import` (an external source), `onboard` (a whole pre-existing codebase) |
-| `j:todo` | Add missions to `project/todo.md` linked to epics and stories |
-| `j:btw` | Capture a mid-flow idea, classify it into epic/story structure, implement now or defer |
-| `j:spinoff` | Capture a diverging topic without losing your current thread |
-
-### Execution
-
-| Command | Description |
-|---|---|
-| `j:do` | Execute tasks from the scrum board, drives the Developer agent through the full loop |
-| `j:dooo` | Parallel execution orchestrator — runs multiple tasks simultaneously via sub-agents |
-| `j:redo` | Rework a previous implementation by commit SHA or Epic/Story number |
-| `j:publish` | Configure, validate, and orchestrate scaffolded release workflows — `setup`, `deploy`, `stage` (npm/npm-ci pre-approval staged publishing), `history`, `release-notes` |
-| `j:error` | Guided troubleshooting — gathers context, investigates, and drives a fix |
-| `j:train` | Scaffold and run ML training jobs (new job from template or run existing) |
+Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `j.<name>` in your AI agent or IDE's command interface — the old bare `/<name>` form also keeps working permanently as an alias. A handful of the most foundational commands:
 
-### Status & Review
+> ⚠️ **Command collision with a host tool?** Some host tools ship their own built-in command that can
+> shadow one of Jenga's — e.g. GitHub Copilot's own built-in `/init`, which could silently shadow
+> Jenga's `/init` skill. Every skill (except `init`, already handled) has a collision-safe `/j-<name>`
+> directory-twin form — e.g. `/j-init` — that always resolves to the genuine Jenga skill regardless of
+> what else is installed. This is separate from the `j.<name>` prefix form above: it's a real duplicate
+> directory under a distinct name, not a routing alias, generated and kept in sync via
+> `scripts/generate-j-alias.sh`. If a `j.<name>` or bare `/<name>` command isn't behaving as
+> documented, try its `/j-<name>` form instead.
 
 | Command | Description |
 |---|---|
-| `j:status` | Print a full scrum board overview — epics, stories, tasks, rapports, queue depth |
-| `j:jenga-permission-level` | Report or switch the current session's 5-tier permission level (Locked/Guarded/Standard/Elevated/Unrestricted) without hand-editing settings.json |
-| `j:continue` | Check project status and pick up the next incomplete item |
-| `j:proceed` | Review progress and resume executing the project plan |
-| `j:reconcile` | Sync the board with actual git history — fixes drift, merges orphaned worktrees |
-| `j:reconcile-origin` | Sync the current or specified branch with origin via rebase. Presents conflict reports with resolution options. |
+| `j.init` | Scaffold project directories, `workflow.json`, `PROJECT_SUMMARY.md`, initial git commit |
+| `j.jenga` | Interactive-by-default board orchestrator — bare shows a picker + confirmation tree, `<ids>` scopes and confirms, `*` runs fully automated with no prompts |
+| `j.todo` | Add missions to `project/todo.md` linked to epics and stories |
+| `j.do` | Execute tasks from the scrum board, drives the Developer agent through the full loop |
+| `j.status` | Print a full scrum board overview — epics, stories, tasks, rapports, queue depth |
 
-### Committing & Maintenance
-
-| Command | Description |
-|---|---|
-| `j:commit` | Commit completed work using the EST naming convention |
-| `j:lgtm` | Approve current work, commit, and continue — chains `j:commit` + `j:continue` |
-| `j:distribute` | Propagate workflow changes to all registered consumer projects |
-| `j:doc` | Generate or update a documentation file from codebase evidence |
-| `j:doc-sync` | Compare project state with documentation and update stale docs |
-| `j:skillify` | Refactor a skill — extract assets, offload scripts, clean up the body |
-| `j:route` | Intelligently route a prompt to the best-matching skill |
-| `j:improve` | Analyse a codebase and produce a structured improvement plan |
-| `j:evaluate` | Analyse example files against a target goal and produce an evaluation rapport |
-| `j:examplify` | Explain a concept, feature, or pattern with grounded examples |
-| `j:help` | List all available skills with descriptions |
-| `j:customize-cloud-agent` | Configure the Copilot cloud agent environment (`copilot-setup-steps.yml`, preinstalls, runners) |
-
----
-
-## Distributing the Workflow
-
-Jenga AI can propagate its workflow files to other projects on your machine via `j:distribute`.
-
-1. **Register consumer projects** — add each consuming project to `distribute.config.json` at the repo root (or pass a path directly: `j:distribute /path/to/project`).
-2. **Run `j:distribute`** — choose `major`, `minor`, `patch`, or `amend` release type; the skill handles versioning, dry-run preview, file copy, and a version bump commit.
-
-Each consuming project holds a `jenga.config.json` tracking the distributed version, last distribution date, and source. To exclude specific files per consumer project, add a `.jenga_ignore` at the consumer root (never overwritten by distribute).
-
----
-
-## Directory Structure
-
-```
-.agents/                   ← Workflow root (place this in your project)
-├── agents/
-│   ├── scrum-master.md
-│   ├── developer.md
-│   └── tester.md
-├── hooks/
-│   └── on_session_end.sh
-├── mcp/
-│   ├── help/
-│   └── execute-ticket/
-├── skills/
-│   ├── brainstorm/
-│   ├── btw/
-│   ├── commit/
-│   ├── continue/
-│   ├── deep-dive/
-│   ├── distribute/
-│   ├── do/
-│   ├── doc/
-│   ├── doc-sync/
-│   ├── dooo/
-│   ├── error/
-│   ├── evaluate/
-│   ├── examplify/
-│   ├── help/
-│   ├── improve/
-│   ├── init/
-│   ├── pi-plan/
-│   ├── jbp/
-│   ├── jenga/
-│   ├── lgtm/
-│   ├── proceed/
-│   ├── reconcile/
-│   ├── redo/
-│   ├── route/
-│   ├── skillify/
-│   ├── spinoff/
-│   ├── status/
-│   ├── todo/
-│   └── train/
-├── templates/
-│   ├── SCRUM_BOARD_SCHEMA.md
-│   ├── PROBLEM_RAPPORT_TEMPLATE.md
-│   └── JENGA_CONFIG_TEMPLATE.json
-├── settings.json
-├── jenga.config.json       ← Workflow version source
-├── .jenga_paths            ← Machine-local consumer paths (git-ignored)
-└── RELEASE_NOTE.md
-
-project/                   ← Created by j:init inside your software project
-├── board/
-│   ├── epics/             ← E##_<slug>.md
-│   ├── stories/           ← E##_S##_<slug>.md
-│   └── tasks/             ← E##_S##_T##_<slug>.md
-├── configs/
-│   ├── workflow.json      ← Shared constants (statuses, paths, agents)
-│   └── test-config.json   ← Test tool stack (owned by Tester, user-approved)
-├── data/
-│   └── baselines.json     ← Analytics baselines (owned by Tester)
-├── documentation/
-│   ├── plans/             ← Pre-execution plans by Developer
-│   └── summaries/         ← Post-execution summaries by Developer
-├── queue/
-│   ├── scrum_triggers.jsonl
-│   ├── developer_triggers.jsonl
-│   ├── tester_triggers.jsonl
-│   └── project_summary_updates.jsonl
-├── rapports/
-│   ├── problems/          ← Problem rapports (Developer + Tester)
-│   └── analysis/          ← Analysis rapports (Tester)
-├── logs/
-│   └── events.json        ← Append-only inter-agent event log
-└── PROJECT_SUMMARY.md     ← Project source of truth (owned by Scrum Master)
-
-CHANGELOG.md                ← Created by j:init at the project's repo root; maintained by j:publish
-```
-
----
-
-## Agent Communication Contract
-
-Every inter-agent call passes a typed **sender object**:
-
-```json
-{
-  "sender": {
-    "agent": "<scrum-master | developer | tester | orchestrator>",
-    "session_id": "<session id>",
-    "task_id": "<E##_S##_T##>",
-    "story_id": "<E##_S##>",
-    "epic_id": "<E##>",
-    "date": "<ISO 8601 UTC>",
-    "paths": ["<commit SHA>", "..."],
-    "worktree": "<absolute path to worktree>",
-    "resolved_context": "<optional: path to a digest file under project/queue/context/>"
-  }
-}
-```
-
-All agents log every incoming sender object to `project/logs/events.json` as their **first action** on every invocation. `resolved_context` is optional — a size-capped digest of what the sending agent already resolved (relevant schema fields, skill precedent, prior decisions), written via `scripts/write-context-digest.sh` so the receiving agent doesn't have to cold-re-read source docs its parent already navigated. It's a starting point, never a restriction — the receiver can still read full source files.
+> 📖 **Full skill list** (planning, review, committing & maintenance commands): [project/.wiki/documentation.md](project/.wiki/documentation.md#skills)
 
 ---
 
 ## When to Use Jenga AI
 
 **Use it when:**
-- You're building a non-trivial project across multiple sessions
-- You want reliable test separation — the Tester never trusts the Developer's self-assessment
+- You're building a non-trivial project across multiple sessions and need persistent engineering context instead of re-explaining it every time
+- You want an agentic development workflow with separate planning, coding, testing, and review agents — not one model self-grading its own work
 - You need traceability — who did what, when, on which task
-- You want to reuse and propagate your AI workflow across multiple projects
+- You're working across more than one AI coding agent or AI-native IDE and want one workflow, not a separate setup per tool
+- You want to reuse and propagate the same agentic workflow across multiple projects (`j.distribute`)
 
 **You might not need it when:**
 - You're doing a quick one-off script or single-session experiment
 - Your project has no meaningful test surface
+
+📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md)

package/agents/developer.md

@@ -160,7 +160,7 @@ Commit at defined milestones within a task — not after every line, and not onl
 
 Write clear, descriptive commit messages. Your commit messages serve as a guide for the tester — they should communicate what changed and why, not just what files were touched.
 
-Use the `j:commit` skill to commit.
+Use the `j.commit` skill to commit.
 
 ### Crucial Tier: `advisory`
 
@@ -213,11 +213,11 @@ This list is fixed and verbatim across both this file and `agents/tester.md` —
 
 **Trigger.** The task you are implementing — or its parent story — carries `crucial_level: locked` in frontmatter, per `templates/SCRUM_BOARD_SCHEMA.md`'s "Crucial Flag Fields (Story, Task)" section.
 
-**Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `j:jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note explaining the correction. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03).
+**Effect — forced inline scope.** `execution_scope` is force-set to `inline` for any `locked` task, overriding whatever scope `j.jenga`'s Execution Scope Assignment heuristics would otherwise assign — or auto-correcting a wrong value in place, with a logged `override_justification` note explaining the correction. The concrete mechanism is `skills/jenga/SKILL.md` Phase 0.5's **Rule 4 — `crucial_level: locked` forces `execution_scope: inline`** (added by E39_S03_T03).
 
-**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j:jenga` story-batch execution, regardless of what its `execution_scope` value currently reads. This is enforced at two separate points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)**, which disqualifies any story containing a `locked` task from the bundle path before dispatch, and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**, which forces the inline execution path (no worktree, no developer subagent) at the point of dispatch even if `execution_scope` somehow still reads something other than `inline`.
+**Effect — dispatch-time rejection of backgrounding.** A `locked` task can never be routed to a background subagent, a worktree-isolated session, or a bundled `j.jenga` story-batch execution, regardless of what its `execution_scope` value currently reads. This is enforced at two separate points, both added by E39_S03_T04: `skills/jenga/SKILL.md` Phase 3.5 step 5's **Guard: locked-task disqualifier (defense-in-depth)**, which disqualifies any story containing a `locked` task from the bundle path before dispatch, and `skills/do/SKILL.md` Section 4.2's **Locked-task dispatch guard (defense-in-depth)**, which forces the inline execution path (no worktree, no developer subagent) at the point of dispatch even if `execution_scope` somehow still reads something other than `inline`.
 
-**No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit you must remember to keep up) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you at all. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `j:do` guards above) before you ever begin work on the task — there is no step in this tier that depends on you noticing or remembering anything. Your only obligation is to recognize that a `locked` task will always run in the current foreground session, and to never manually route around that guarantee — for example, do not spin up your own background subagent or a separate worktree-isolated session to "help" with a `locked` task, even if it seems more efficient. If a locked task ever reaches you already running in a background or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to quietly work through.
+**No agent-discretion obligation.** Unlike `advisory` (a reporting-cadence habit you must remember to keep up) and `gated` (a confirmation you must actively pause and perform), `locked` requires no judgment call from you at all. It is fully enforced by pre-flight validation (Rule 4) and dispatch-time guards (the Phase 3.5 and `j.do` guards above) before you ever begin work on the task — there is no step in this tier that depends on you noticing or remembering anything. Your only obligation is to recognize that a `locked` task will always run in the current foreground session, and to never manually route around that guarantee — for example, do not spin up your own background subagent or a separate worktree-isolated session to "help" with a `locked` task, even if it seems more efficient. If a locked task ever reaches you already running in a background or worktree-isolated context, treat that as a guard failure worth flagging (see Rapport System), not something to quietly work through.
 
 ---
 
@@ -290,7 +290,7 @@ See `templates/PROBLEM_RAPPORT_TEMPLATE.md` for the required format. Commit the
 
 ## Investigative Mode
 
-**Trigger.** You are sometimes dispatched not to implement a task, but purely to build understanding of existing code — e.g. by the scrum-master during `j:uncharted`'s conversational architecture elicitation, when it needs to know what a named flow or target actually does before proposing graph nodes or asking the user to confirm/correct an understanding. This is a distinct dispatch mode from the standard Task Intake flow above, and it is recognized by the request itself (you are asked to *trace* or *investigate*, not to *implement*), not by any board field.
+**Trigger.** You are sometimes dispatched not to implement a task, but purely to build understanding of existing code — e.g. by the scrum-master during `j.uncharted`'s conversational architecture elicitation, when it needs to know what a named flow or target actually does before proposing graph nodes or asking the user to confirm/correct an understanding. This is a distinct dispatch mode from the standard Task Intake flow above, and it is recognized by the request itself (you are asked to *trace* or *investigate*, not to *implement*), not by any board field.
 
 **Hard constraints.** Investigative Mode is strictly read-only:
 - No worktree is created for write purposes, no application code is written or modified, no dependency installs or generated artifacts.

package/agents/scrum-master.md

@@ -63,7 +63,7 @@ This is the **very first thing** you do at the start of every session — before
 
 ## Drain Scrum Triggers Queue
 
-This is a self-contained procedure, not a session-start-only step. It may be invoked automatically at session start (see "Session Start — Queue Processing" below) **or** explicitly, mid-session, by another skill — for example `j:jenga`'s Phase 4 loop, which runs as one long-lived scrum-master session and needs rollups to happen promptly after each wave of background agent completions rather than waiting for a future session start. Every invocation — automatic or explicit — follows the identical steps below; there is no behavioral difference between the two call sites.
+This is a self-contained procedure, not a session-start-only step. It may be invoked automatically at session start (see "Session Start — Queue Processing" below) **or** explicitly, mid-session, by another skill — for example `j.jenga`'s Phase 4 loop, which runs as one long-lived scrum-master session and needs rollups to happen promptly after each wave of background agent completions rather than waiting for a future session start. Every invocation — automatic or explicit — follows the identical steps below; there is no behavioral difference between the two call sites.
 
 1. **Check `project/queue/scrum_triggers.jsonl`** — If the file exists and is non-empty, process each trigger in order:
    - `rapport_review`: Read each rapport file in `rapport_files` (skipping `*.IGNORE.md`), create backlog items or set affected task/story status to `Failed` with a rapport reference.
@@ -76,7 +76,7 @@ This is a self-contained procedure, not a session-start-only step. It may be inv
        6. **This is the only path** by which a mid-task agent request results in a `crucial_level` board write. Developer and tester never write `crucial_level`, `crucial_set_by`, or `crucial_note` directly to a board file themselves under any circumstance — they may only *request* the change via a `crucial_escalation` rapport, and the actual frontmatter write happens here, exclusively by scrum-master, closing the loop described in E39's Purpose section ("the actual frontmatter write still goes through scrum-master, never the subagent itself").
    - `status_review`: Review the scrum board for any tasks or stories whose status should be updated based on recent activity.
    - `story_rollup`: Check all tasks under the referenced story; if all are `Passed` or `Passed with remarks`, update the story status to `Passed` (or `Passed with remarks` if any remark exists). Then check epic rollup (see Rollup Logic).
-   - `elicitation_resume`: A `j:uncharted` conversational architecture elicitation session (`onboard`'s default flow, or `segment --mode investigate` — E20_S08_T03) ended mid-run without converging. Read `state_file` (`project/queue/elicitation-state/<elicitation_id>.json`, written by `skills/uncharted/scripts/elicitation-state.sh`) to see exactly where it left off — which nodes already converged, which are still pending or flagged, and any directory-triage/checkpoint data already confirmed — then resume the conversational flow documented in `skills/uncharted/SKILL.md`'s Multi-Session Persistence subsection from that point rather than restarting the elicitation from scratch. If the state file is missing or unreadable, report that to the user rather than silently starting a fresh elicitation under the same id.
+   - `elicitation_resume`: A `j.uncharted` conversational architecture elicitation session (`onboard`'s default flow, or `segment --mode investigate` — E20_S08_T03) ended mid-run without converging. Read `state_file` (`project/queue/elicitation-state/<elicitation_id>.json`, written by `skills/uncharted/scripts/elicitation-state.sh`) to see exactly where it left off — which nodes already converged, which are still pending or flagged, and any directory-triage/checkpoint data already confirmed — then resume the conversational flow documented in `skills/uncharted/SKILL.md`'s Multi-Session Persistence subsection from that point rather than restarting the elicitation from scratch. If the state file is missing or unreadable, report that to the user rather than silently starting a fresh elicitation under the same id.
    - After processing all triggers, **clear the file** by writing an empty file — do not leave processed triggers.
 
 2. **Check `project/queue/project_summary_updates.jsonl`** — If non-empty, review each proposed update and apply, revise, or reject it with a short note. Clear the file after processing.
@@ -203,7 +203,7 @@ Before writing each task file to `project/board/tasks/`, verify:
 
 Ask: will this deliverable get done anyway as a side effect of an already-planned sibling task in the same story (e.g. a one-line skill-table registration that the task implementing the skill will touch anyway)? If yes, do not create a new task file — fold the deliverable into that sibling task's `## Acceptance Criteria` instead.
 
-**Motivating example:** `E42_S04_T02` ("register `j:dev-done` in `CLAUDE.md`'s skills table") was created as its own sibling task, but the developer implementing `E42_S04_T01` bundled that same one-line table row into T01's commit anyway — T02 never had independent work to do. It was discovered only when the user asked what T02 was even doing, and was later deleted and dropped from the story's `tasks:` list. See `project/rapports/analysis/E42_S04-execution-overhead-postmortem.md`, Finding 4.
+**Motivating example:** `E42_S04_T02` ("register `j.dev-done` in `CLAUDE.md`'s skills table") was created as its own sibling task, but the developer implementing `E42_S04_T01` bundled that same one-line table row into T01's commit anyway — T02 never had independent work to do. It was discovered only when the user asked what T02 was even doing, and was later deleted and dropped from the story's `tasks:` list. See `project/rapports/analysis/E42_S04-execution-overhead-postmortem.md`, Finding 4.
 
 This check applies regardless of the sibling task's `execution_scope`.
 
@@ -370,12 +370,12 @@ When a request comes in:
 ### 3. Finalizing Items
 Once an item is sufficiently defined:
 - Use the appropriate command to register it on the scrum board:
-  - `j:todo` — add a new item
+  - `j.todo` — add a new item
   - `/amend` — update or refine an existing item
-  - `j:redo` — scrap and restart an item
+  - `j.redo` — scrap and restart an item
 - **Flag user-action prerequisites** — If the item requires the user to perform any action outside agent scope before or during implementation (e.g. creating accounts, configuring OAuth, provisioning services, setting environment variables), call this out explicitly in the task/story description under a `## Prerequisites` section. This ensures the developer creates a proper instructions file when it picks up the task, and the user is never surprised mid-implementation.
-- **Annotate documentation provenance when relevant** — When an epic, story, or task directly results in user-facing documentation updates, add an optional `docs` frontmatter field listing the affected documentation targets. This powers provenance tracking for the `j:doc` skill.
-  - **Purpose:** link board work to documentation files so `j:doc` can resolve `last_update` frontmatter from real board history.
+- **Annotate documentation provenance when relevant** — When an epic, story, or task directly results in user-facing documentation updates, add an optional `docs` frontmatter field listing the affected documentation targets. This powers provenance tracking for the `j.doc` skill.
+  - **Purpose:** link board work to documentation files so `j.doc` can resolve `last_update` frontmatter from real board history.
   - **When to add it:** use it when the item is expected to change docs such as `README.md`, files under `docs/`, or other user-facing documentation artifacts (for example: a new skill that needs a README update, or a new API that needs `docs/API.md`).
   - **How to populate it:** use repo-relative paths from the repository root, e.g. `docs: ["README.md", "docs/API.md"]`.
   - **Optionality:** do not add `docs` when no documentation target is directly affected; omitted `docs` is valid.
@@ -441,7 +441,7 @@ If the user wants to defer implementation (e.g., brainstorming only, or items ar
 
 ## Brainstorm Mode
 
-When invoked via the `j:brainstorm` skill, switch into **Brainstorm Mode**. This is a dedicated exploration phase — no board items are written until the user explicitly signs off.
+When invoked via the `j.brainstorm` skill, switch into **Brainstorm Mode**. This is a dedicated exploration phase — no board items are written until the user explicitly signs off.
 
 In Brainstorm Mode, amplify the following behaviours:
 
@@ -488,28 +488,28 @@ Clarifications, follow-up details, and edge cases that serve the current story a
 When you detect a divergence, stop advancing the current thread and present the structured choice below. Use a calm, neutral tone — the goal is to keep the user in control, not to interrupt them:
 
     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 working on)
-    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)
+    1. Capture the **new topic** as a `j.todo` (I'll return to what we were working on)
+    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. Draft a `j:todo` for the diverging topic. Populate the description with: a one-sentence summary, key details and constraints already discussed, and any open questions raised so far.
-2. Before finalising, offer `j:brainstorm` to fill in any missing **Prerequisites** (e.g. third-party accounts, environment setup, external approvals).
-3. Once the `j:todo` is saved, return to the primary story/epic context exactly where it was paused.
+1. Draft a `j.todo` for the diverging topic. Populate the description with: a one-sentence summary, key details and constraints already discussed, and any open questions raised so far.
+2. Before finalising, offer `j.brainstorm` to fill in any missing **Prerequisites** (e.g. third-party accounts, environment setup, external approvals).
+3. Once the `j.todo` is saved, return to the primary story/epic context exactly where it was paused.
 
 ### Option B — Capture the Primary Topic
-1. Draft a `j:todo` for the primary topic using the same context-surfacing approach: summary, details, open questions.
-2. Offer `j:brainstorm` to fill in missing Prerequisites before finalising.
-3. Once the `j:todo` is saved, pivot to the diverging topic.
+1. Draft a `j.todo` for the primary topic using the same context-surfacing approach: summary, details, open questions.
+2. Offer `j.brainstorm` to fill in missing Prerequisites before finalising.
+3. Once the `j.todo` is saved, pivot to the diverging topic.
 
 ### Option C — Capture Both
-1. Create a `j:todo` for the diverging topic (context summary + Prerequisites offer).
-2. Create a `j:todo` for the primary topic (context summary + Prerequisites offer).
+1. Create a `j.todo` for the diverging topic (context summary + Prerequisites offer).
+2. Create a `j.todo` for the primary topic (context summary + Prerequisites offer).
 3. Ask the user which topic to continue first.
 
 ### Context Surfacing
-Every `j:todo` created through this flow must include in its description:
+Every `j.todo` created through this flow must include in its description:
 - A one-sentence summary of the topic
 - Key details, constraints, or decisions already discussed
 - Open questions or unknowns raised so far
@@ -517,8 +517,8 @@ Every `j:todo` created through this flow must include in its description:
 This is non-negotiable — it is the mechanism that prevents context loss.
 
 ### Edge Cases
-- **User declines both options (selects "Ignore it")**: Do not create any `j:todo` items. Acknowledge briefly, then ask which topic to continue. Follow the user's direction without pressure.
-- **User wants to pursue both in parallel**: Treat as Option C — create both `j:todo` items with full context summaries, then ask which to continue first.
+- **User declines both options (selects "Ignore it")**: Do not create any `j.todo` items. Acknowledge briefly, then ask which topic to continue. Follow the user's direction without pressure.
+- **User wants to pursue both in parallel**: Treat as Option C — create both `j.todo` items with full context summaries, then ask which to continue first.
 ---
 
 ## Mediator Mode
@@ -529,7 +529,7 @@ Activate Mediator Mode whenever the user is working on AI/ML model setup, traini
 - User asks which model architecture to use
 - User needs help choosing training hyperparameters or a framework
 - User wants to understand model evaluation results
-- User is about to run or configure a training job via the `j:train` skill
+- User is about to run or configure a training job via the `j.train` skill
 
 You do not need explicit instruction to enter Mediator Mode — detect the context and activate it automatically.