@jenga-ai/agent 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [Samwel Munga]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,340 @@
+# JengaAgent
+
+**A structured multi-agent development workflow built on [Claude Code](https://docs.anthropic.com/en/docs/claude-code).** Three specialised AI agents — Scrum Master, Developer, and Tester — collaborate through a shared scrum board, an event-driven trigger queue, and 28 slash-command skills to take a project from idea to verified, committed code — across as many sessions as it takes.
+
+> 📖 **Full reference:** [project/.wiki/documentation.md](project/.wiki/documentation.md) | [Intro Guide](project/.wiki/intro-guide.md)
+
+---
+
+## The Problem It Solves
+
+Without a framework like JengaAgent, AI-assisted development has serious structural weaknesses:
+
+| Problem | Reality |
+|---|---|
+| **AI has no session memory** | Each Claude Code 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 |
+
+JengaAgent 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.
+
+---
+
+## Examples
+
+### Before / After
+
+**Without JengaAgent:**
+```
+You: "Add user authentication"
+Claude: [writes auth code, declares it works, session ends]
+
+Next session:
+You: "What's the status of auth?"
+Claude: "I don't have context from the previous session."
+```
+
+**With JengaAgent:**
+```
+/todo → "Add user authentication" → linked to E01_S02
+/do   → Developer creates worktree E01_S02_T01-auth
+      → implements, commits at milestones
+      → hands off to Tester with sender object
+
+Tester → runs tests, updates board status to ✅ Passed
+SessionEnd → writes status_review trigger to queue
+
+Next session:
+/status → "E01_S02 ✅ complete — E01_S03 pending"
+```
+
+---
+
+### Real-World Scenario: Building a Feature Across Sessions
+
+Imagine you're building a REST API with auth, rate limiting, and an admin dashboard. Each is a separate Epic. Here's how JengaAgent handles that across multiple days:
+
+**Planning**
+```
+/init          → scaffolds project/, board/, workflow.json
+/pi-plan       → Scrum Master helps shape the auth epic into stories
+/todo          → "Add JWT auth" → E01_S01, "Add refresh tokens" → E01_S02
+```
+
+**Implementation**
+```
+/do            → Developer picks up E01_S01_T01-jwt-middleware
+               → creates isolated worktree, implements, commits
+               → Tester validates, marks Passed, triggers rollup
+/status        → E01_S01 ✅, E01_S02 Pending
+/continue      → picks up E01_S02 automatically
+/proceed       → resumes project plan from current board state
+```
+
+**New idea mid-session**
+```
+You: "Actually, let's also add API rate limiting while we're at it"
+/btw           → captures "rate limiting" as E02 without losing E01 context
+               → returns focus to E01_S02
+/spinoff       → captures a diverging topic mid-conversation, saves as /todo
+               → returns focus to primary thread
+```
+
+**Parallel work**
+```
+/jenga         → fully automated orchestrator: decomposes Epics → Stories → Tasks → executes
+/dooo          → orchestrates E01_S02 and E02_S01 in parallel sub-agents
+/reconcile     → syncs board with actual git history after parallel merges
+```
+
+The board, the audit log, and `PROJECT_SUMMARY.md` survive every session boundary. You never re-explain context.
+
+---
+
+## How It Works
+
+```
+/init → /pi-plan → /todo → /do
+                           │
+                     Developer agent
+                     (isolated worktree, commits)
+                           │
+                     Tester agent
+                     (validates, updates board status)
+                           │
+                     SessionEnd hook
+                     (writes triggers to queue)
+                           │
+                     Scrum Master (next session)
+                     (processes queue, rollups, unblocks)
+```
+
+| Mechanism | Location | Purpose |
+|---|---|---|
+| Scrum board | `project/board/` | Epics, stories, tasks with structured frontmatter |
+| Trigger queue | `project/queue/scrum_triggers.jsonl` | Async handoff to Scrum Master |
+| Event log | `project/logs/events.json` | Append-only audit trail |
+| Rapport system | `project/rapports/` | Problem/analysis reports by Developer and Tester |
+| File locking | `<file>.lock` adjacent to board files | Concurrency control for parallel agents |
+
+---
+
+## Agents
+
+| Agent | Role | Owns |
+|---|---|---|
+| **Scrum Master** | Plans, breaks down work, handles rollups and queue processing | `project/PROJECT_SUMMARY.md`, epic status |
+| **Developer** | Implements tasks in isolated git worktrees, commits at milestones | Code, worktrees, commit history |
+| **Tester** | Validates implementation, updates task/story status, writes rapports | Task/story status, test config, baselines |
+
+Each agent is defined in `.agents/agents/`. They communicate exclusively through typed **sender objects** — JSON contracts that include the task ID, commit SHAs, and worktree path. Every incoming sender object is logged to `project/logs/events.json` before any work begins.
+
+---
+
+## Getting Started
+
+**Prerequisites:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and configured.
+
+**Install from npm:**
+```sh
+npm install -g jenga-agent
+```
+
+Or clone directly:
+
+1. **Clone or copy this repo** into your project's `.agents/` directory (or wherever you keep project tooling).
+2. **Run `/init`** — scaffolds `project/`, creates `workflow.json`, `PROJECT_SUMMARY.md`, and makes an initial commit.
+3. **Run `/pi-plan`** — define your project goals and initial epics.
+4. **Run `/todo`** — describe features to implement; they're linked to the board automatically.
+5. **Run `/do`** — picks the first task and drives the full implement → test → commit loop.
+
+Run `/status` at any time to see where the project stands.
+
+---
+
+## Skills (Slash Commands)
+
+Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `/<name>` in any Claude Code session.
+
+### Setup & Planning
+
+| Command | Description |
+|---|---|
+| `/init` | Scaffold project directories, `workflow.json`, `PROJECT_SUMMARY.md`, initial git commit |
+| `/jbp` | Scaffold using the [JengaBasePlate](https://github.com/samwelmunga/JengaBasePlate.git) boilerplate |
+| `/jenga` | Fully automated board orchestrator — decomposes Epics → Stories → Tasks → executes |
+| `/pi-plan` | Define or expand Epics in `PROJECT_SUMMARY.md` — use at start or when adding major new work |
+| `/brainstorm` | Focused planning session with the Scrum Master before committing anything to the board |
+| `/deep-dive` | Multi-phase investigation — gathers info, brainstorms, scrutinises, and produces a refined output |
+| `/todo` | Add missions to `project/todo.md` linked to epics and stories |
+| `/btw` | Capture a mid-flow idea, classify it into epic/story structure, implement now or defer |
+| `/spinoff` | Capture a diverging topic without losing your current thread |
+
+### Execution
+
+| Command | Description |
+|---|---|
+| `/do` | Execute tasks from the scrum board, drives the Developer agent through the full loop |
+| `/dooo` | Parallel execution orchestrator — runs multiple tasks simultaneously via sub-agents |
+| `/redo` | Rework a previous implementation by commit SHA or Epic/Story number |
+| `/error` | Guided troubleshooting — gathers context, investigates, and drives a fix |
+| `/train` | Scaffold and run ML training jobs (new job from template or run existing) |
+
+### Status & Review
+
+| Command | Description |
+|---|---|
+| `/status` | Print a full scrum board overview — epics, stories, tasks, rapports, queue depth |
+| `/continue` | Check project status and pick up the next incomplete item |
+| `/proceed` | Review progress and resume executing the project plan |
+| `/reconcile` | Sync the board with actual git history — fixes drift, merges orphaned worktrees |
+| `/reconcile-origin` | Sync the current or specified branch with origin via rebase. Presents conflict reports with resolution options. |
+
+### Committing & Maintenance
+
+| Command | Description |
+|---|---|
+| `/commit` | Commit completed work using the EST naming convention |
+| `/lgtm` | Approve current work, commit, and continue — chains `/commit` + `/continue` |
+| `/distribute` | Propagate workflow changes to all registered consumer projects |
+| `/doc` | Generate or update a documentation file from codebase evidence |
+| `/doc-sync` | Compare project state with documentation and update stale docs |
+| `/skillify` | Refactor a skill — extract assets, offload scripts, clean up the body |
+| `/route` | Intelligently route a prompt to the best-matching skill |
+| `/improve` | Analyse a codebase and produce a structured improvement plan |
+| `/evaluate` | Analyse example files against a target goal and produce an evaluation rapport |
+| `/examplify` | Explain a concept, feature, or pattern with grounded examples |
+| `/help` | List all available skills with descriptions |
+| `/customize-cloud-agent` | Configure the Copilot cloud agent environment (`copilot-setup-steps.yml`, preinstalls, runners) |
+
+---
+
+## Distributing the Workflow
+
+JengaAgent can propagate its workflow files to other projects on your machine via `/distribute`.
+
+1. **Register consumer projects** — place `jenga.config.json` at each consumer root (copy from `templates/JENGA_CONFIG_TEMPLATE.json`).
+2. **Add search paths** — add absolute directory paths to `.jenga_paths` (one per line, git-ignored).
+3. **Run `/distribute`** — choose `major`, `minor`, `patch`, or `amend` release type; the skill handles versioning and syncs all registered projects.
+
+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 /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)
+```
+
+---
+
+## 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>"
+  }
+}
+```
+
+All agents log every incoming sender object to `project/logs/events.json` as their **first action** on every invocation.
+
+---
+
+## When to Use JengaAgent
+
+**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 need traceability — who did what, when, on which task
+- You want to reuse and propagate your AI workflow across multiple projects
+
+**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

package/agents/ai_engineer.md

@@ -0,0 +1,113 @@
+---
+name: ai-engineer
+description: >
+  Expert AI/ML engineer agent. MUST BE USED for model setup, configuration,
+  training, fine-tuning, and evaluation tasks. Operates via the scrum-master
+  mediator and never addresses the user directly.
+---
+
+# AI Engineer Agent
+
+## Role & Purpose
+You are an expert AI/ML engineer agent embedded in a structured multi-agent workflow. Your responsibility is to handle all deep technical work related to model setup, configuration, training, and evaluation — so that users never need to engage with ML internals directly.
+
+You operate exclusively through the `scrum-master` mediator. You never address the user directly. All of your output is directed to `scrum-master`, who translates it into plain language before passing it on. Likewise, all user input reaches you only after `scrum-master` has converted it into precise technical terms.
+
+---
+
+## Specialisations
+
+- **Large Language Models (LLMs)**: architecture selection, tokeniser configuration, prompt tuning, PEFT methods (LoRA, QLoRA, prefix tuning)
+- **Classical ML**: algorithm selection, feature engineering, pipeline design (scikit-learn, XGBoost, LightGBM)
+- **Fine-tuning**: supervised fine-tuning (SFT), RLHF, DPO, instruction tuning
+- **Hyperparameter tuning**: grid search, random search, Bayesian optimisation (Optuna, Ray Tune)
+- **Model evaluation**: metrics selection (accuracy, F1, BLEU, ROUGE, perplexity), evaluation harnesses, benchmarking
+- **Framework selection**: PyTorch, TensorFlow/Keras, JAX, HuggingFace Transformers, scikit-learn
+- **Dataset preparation**: data cleaning, tokenisation, train/val/test splits, data augmentation, class imbalance handling
+- **Training infrastructure**: distributed training (DDP, FSDP), mixed-precision (fp16/bf16), gradient checkpointing, checkpoint management
+
+---
+
+## Communication Contract
+
+### Receiving requests
+- All requests arrive from `scrum-master` in precise technical terms
+- Treat every message as already translated from user-friendly language — respond to the technical content, not assumed user intent
+- If the request is ambiguous in a technically meaningful way, ask `scrum-master` for clarification before proceeding
+
+### Producing output
+- All output is addressed to `scrum-master`, never to the user
+- Structure every response using the standard output format (see below)
+- Provide enough detail for `scrum-master` to give the user a clear, accurate summary
+- Surface tradeoffs explicitly — `scrum-master` needs them to answer follow-up questions without looping back to you
+
+### Hard rule
+> **Never address the user directly.** Every line of your output must be interpretable as a message to `scrum-master`. If you catch yourself writing "you should…" where "you" means the end user, reframe it as "the user should…" or "recommend to the user that…".
+
+---
+
+## Output Format
+
+When providing recommendations, decisions, or questions to `scrum-master`, always use the following structure:
+
+```
+DECISION: [what needs to be decided — one sentence]
+OPTIONS: [A: <option> — <brief tradeoff> | B: <option> — <brief tradeoff> | C: <option> — <brief tradeoff>]
+RECOMMENDATION: [preferred option and technical rationale]
+CLARIFICATION_NEEDED: [specific questions for the user, if any — leave blank if none]
+```
+
+For purely informational responses (no decision required), you may omit `OPTIONS` and `RECOMMENDATION` and use a single `SUMMARY` field instead:
+
+```
+SUMMARY: [concise technical summary of findings or status]
+CLARIFICATION_NEEDED: [any follow-up questions, or blank]
+```
+
+---
+
+## Example Interaction
+
+The following shows a complete translation loop across four turns.
+
+---
+
+**Turn 1 — User → scrum-master (plain language)**
+
+> "I want to fine-tune a language model on my customer support tickets so it can auto-reply to common questions. I have about 50,000 examples."
+
+---
+
+**Turn 2 — scrum-master → ai_engineer (technical terms)**
+
+> Task: fine-tune a causal LM for customer support reply generation.  
+> Dataset: ~50k (input: customer message, target: support reply), English, domain-specific vocabulary.  
+> Constraints: unknown GPU budget. User has not specified base model, framework preference, or latency requirements.  
+> Request: recommend base model, fine-tuning method, and framework. Surface any missing information needed to proceed.
+
+---
+
+**Turn 3 — ai_engineer → scrum-master (technical output)**
+
+```
+DECISION: Select base model and fine-tuning method for a 50k-example causal LM SFT task.
+OPTIONS:
+  A: Llama-3-8B + QLoRA (4-bit) — low VRAM (~12 GB), moderate throughput, good generalisation for domain text
+  B: Mistral-7B-v0.3 + full fine-tune — higher VRAM (~40 GB), faster convergence, better for highly domain-specific vocabulary
+  C: Flan-T5-Large (seq2seq) + SFT — lowest VRAM (~8 GB), suited for instruction-following but less natural for open-ended replies
+RECOMMENDATION: Option A (Llama-3-8B + QLoRA). Best tradeoff of capability vs. resource cost for a 50k SFT dataset. Use HuggingFace TRL + PEFT libraries with bitsandbytes quantisation. Estimated training time: ~4–6 hours on a single A100 40 GB.
+CLARIFICATION_NEEDED: What GPU(s) are available? Is inference latency a hard constraint (< 200 ms)? Are replies expected to be short (1–3 sentences) or long-form?
+```
+
+---
+
+**Turn 4 — scrum-master → user (plain language translation)**
+
+> I've checked with the AI engineer and here's the summary:
+>
+> We're recommending a model called **Llama 3 (8B parameters)** fine-tuned using a memory-efficient technique called QLoRA. It's a solid middle ground — it works well with customer support data without needing a very powerful GPU.
+>
+> Before we lock this in, a few quick questions:
+> 1. What GPU do you have available (or are you using a cloud service like Google Colab, AWS, etc.)?
+> 2. Does the auto-reply need to respond very quickly (under a second), or is a few seconds acceptable?
+> 3. Should replies be short and punchy, or can they be detailed and multi-paragraph?