@jenga-ai/agent 1.0.0

package/templates/EXECUTION_PLAN_TEMPLATE.md

@@ -0,0 +1,43 @@
+# Execution Plan: <Title>
+
+**Task ID:** E##_S##_T##
+**Story ID:** E##_S##
+**Epic ID:** E##
+**Date:** YYYY-MM-DD (UTC)
+**Agent:** developer
+**Session ID:** <session_id>
+
+---
+
+## Task Summary
+<Brief description of what this task requires, drawn from the scrum board definition.>
+
+---
+
+## Implementation Approach
+
+<Step-by-step plan for how this task will be implemented. Be specific enough that the tester can understand the intended design.>
+
+1.
+2.
+3.
+
+---
+
+## Files to Change
+
+| File | Planned Change |
+|------|----------------|
+|      |                |
+
+---
+
+## Dependencies & Risks
+
+<List any dependencies on other tasks, external libraries, APIs, or services. Note any known risks or areas of uncertainty.>
+
+---
+
+## Notes
+
+<Any additional context or considerations relevant to this task.>

package/templates/EXECUTION_SUMMARY_TEMPLATE.md

@@ -0,0 +1,50 @@
+# Execution Summary: <Title>
+
+**Task ID:** E##_S##_T##
+**Story ID:** E##_S##
+**Epic ID:** E##
+**Date Completed:** YYYY-MM-DD (UTC)
+**Agent:** developer
+**Session ID:** <session_id>
+
+---
+
+## What Was Implemented
+
+<Brief description of what was built or changed.>
+
+---
+
+## Files Changed
+
+| File | Summary of Changes |
+|------|--------------------|
+|      |                    |
+
+---
+
+## Commits
+
+| SHA | Message |
+|-----|---------|
+|     |         |
+
+---
+
+## Acceptance Criteria Coverage
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+|           |        |       |
+
+---
+
+## Edge Cases & Known Concerns
+
+<Describe any edge cases encountered or known concerns that the tester should be aware of.>
+
+---
+
+## Notes for Tester
+
+<Any specific guidance, setup steps, or context that will help the tester verify this work.>

package/templates/JENGA_CONFIG_TEMPLATE.json

@@ -0,0 +1,23 @@
+{
+  "_schema": "https://github.com/samwelmunga/agents — jenga.config.json v1",
+
+  // Required — must be "jenga"
+  "workflow": "jenga",
+
+  // Workflow version installed in this project.
+  // Format: MAJOR.MINOR.PATCH — bump this when the workflow is updated.
+  "workflow_version": "1.0.0",
+
+  // Directory inside this project where the workflow files live.
+  // Typical values: ".agents" (default) or ".claude"
+  "target_dir": ".agents",
+
+  // Human-readable name for this project (informational only).
+  "project_name": "your-project-name",
+
+  // ISO 8601 date when the workflow was first installed in this project.
+  "created_at": "YYYY-MM-DD",
+
+  // ISO 8601 date of the last workflow sync to this project.
+  "updated_at": "YYYY-MM-DD"
+}

package/templates/PROBLEM_RAPPORT_TEMPLATE.md

@@ -0,0 +1,88 @@
+# Rapport: <Short Problem Description>
+
+**Date:** YYYY-MM-DD (UTC)
+**Agent:** Developer | Tester
+**Related Epic:** <Epic name or N/A>
+**Related Story:** <Story name or N/A>
+**Related Task:** <Task name or N/A>
+**Type:** `conflict` | `implementation_blocker` | `security_concern` | `test_failure` | `analysis`
+
+---
+
+## Sender
+```json
+{
+  "sender": {
+    "agent": "",
+    "session_id": "",
+    "task_id": "",
+    "story_id": "",
+    "epic_id": "",
+    "date": "",
+    "paths": [],
+    "worktree": ""
+  }
+}
+```
+
+---
+
+## Summary
+A one or two sentence description of what the problem is and why it blocked progress or requires attention.
+
+---
+
+## Context
+What was being implemented or tested when this issue was encountered. Include relevant task or story goals.
+
+---
+
+## Problem Description
+A detailed explanation of the issue.
+- **Conflict:** describe both implementations and where they clash
+- **Security concern:** describe the vulnerability or risk
+- **Implementation blocker:** describe what failed and why
+- **Test failure:** describe which tests failed, what was expected, and what was observed
+- **Analysis:** describe the analysis scope, methodology, and findings
+
+---
+
+## Attempts Made
+_Only applicable for `conflict` and `implementation_blocker` types._
+
+### Attempt 1
+What was tried and why it did not work.
+
+### Attempt 2
+What was tried and why it did not work.
+
+### Attempt 3
+What was tried and why it did not work.
+
+---
+
+## Findings
+_Only applicable for `test_failure` and `analysis` types._
+
+| # | Finding | Severity | Notes |
+|---|---------|----------|-------|
+| 1 | | | |
+
+---
+
+## Impact
+What cannot proceed until this is resolved. Which tasks, stories, or epics are blocked.
+
+---
+
+## Suggested Next Steps
+Concrete suggestions for how a human or another agent could resolve this. Be specific.
+
+---
+
+## Ignore Log
+_Only populated by the developer when this rapport is marked `.IGNORE.md`._
+
+**Ignored by:** Developer
+**Date:** YYYY-MM-DD (UTC)
+**Reason:**

package/templates/SCRUM_BOARD_SCHEMA.md

@@ -0,0 +1,311 @@
+# Scrum Board Schema
+
+This document is the authoritative reference for all scrum board files. Every agent that creates, reads, or updates board items must follow this schema exactly.
+
+---
+
+## Directory Layout
+
+```
+project/
+  board/
+    epics/          Epic files: E##_<slug>.md
+    stories/        Story files: E##_S##_<slug>.md
+    tasks/          Task files: E##_S##_T##_<slug>.md
+  instructions/     User-action prerequisite files: E##_S##_T##_INSTRUCTIONS.md
+                    (created on first use — not pre-provisioned)
+  configs/
+    workflow.json   Shared constants (statuses, paths, rapport types)
+  data/
+    baselines.json  Analytics baselines (owned by tester)
+  documentation/
+    plans/          Pre-execution plans: E##_S##_T##-plan.md (written by developer before implementation)
+    summaries/      Post-execution summaries: E##_S##_T##-summary.md (written by developer before invoking tester)
+  queue/
+    scrum_triggers.jsonl         Trigger queue for scrum master
+    developer_triggers.jsonl     Trigger queue for developer agent
+    tester_triggers.jsonl        Trigger queue for tester agent
+    project_summary_updates.jsonl Proposed PROJECT_SUMMARY.md edits
+    .session_handoff.json        Transient inter-session handoff (written by agent, consumed by on_session_end.sh)
+  rapports/
+    problems/       Problem rapports from developer and tester
+    analysis/       Analysis rapports from tester
+  logs/
+    events.json     Append-only inter-agent event log
+```
+
+> **Note:** `project/epics/` and `project/stories/` and `project/tasks/` are legacy paths from earlier skills. All new board items are written under `project/board/`. Skills and agents that reference the legacy paths should migrate to `project/board/` when next touched.
+
+---
+
+## ID & Filename Conventions
+
+| Type  | ID Format     | Filename                          |
+|-------|---------------|-----------------------------------|
+| Epic  | `E##`         | `E##_<slug>.md`                   |
+| Story | `E##_S##`     | `E##_S##_<slug>.md`               |
+| Task  | `E##_S##_T##` | `E##_S##_T##_<slug>.md`           |
+
+- Numbers are zero-padded to two digits: `E01`, `S03`, `T07`
+- `<slug>` is a short lowercase kebab-case title derived from the item title
+- Example: `E02_S04_T01_add-jwt-middleware.md`
+
+---
+
+## Status Values
+
+All status fields must use one of the following exact strings:
+
+| Status               | Meaning                                                    |
+|----------------------|------------------------------------------------------------|
+| `Pending`            | Created, not yet started                                   |
+| `In Progress`        | Actively being worked on                                   |
+| `Passed`             | All tests passed, no findings                              |
+| `Passed with remarks`| Tests passed but non-blocking findings exist               |
+| `Failed`             | Tests did not pass                                         |
+| `Rejected`           | Deliberately rejected — not a test failure                 |
+| `Blocked`            | Cannot proceed; human intervention required                |
+
+Only the **tester agent** may write status values to story and task files. Only the **scrum master** may write status values to epic files and may update story status as part of rollup.
+
+---
+
+## File Formats
+
+### Epic — `E##_<slug>.md`
+
+```markdown
+---
+id: E##
+title: <Title>
+status: Pending
+date_created: YYYY-MM-DD
+date_started:
+date_completed:
+dates_previously_completed:  # comma-separated list, e.g. 2026-01-15, 2026-03-22
+reopened_on:                 # comma-separated list, e.g. 2026-02-01, 2026-04-10
+reopened_reason:             # comma-separated list, e.g. "Scope expanded", "Bug found post-release"
+docs: []                     # optional list of repo-relative documentation paths, e.g. ["README.md", "docs/API.md"]
+stories:
+  - E##_S##
+  - E##_S##
+---
+
+# Epic: <Title>
+
+## Purpose
+<What this epic achieves and why.>
+
+## Definition of Done
+- <Concrete, testable criterion>
+- <Concrete, testable criterion>
+```
+
+### Story — `E##_S##_<slug>.md`
+
+```markdown
+---
+id: E##_S##
+epic_id: E##
+title: <Title>
+status: Pending
+date_created: YYYY-MM-DD
+date_started:
+date_completed:
+dates_previously_completed:  # comma-separated list, e.g. 2026-01-15, 2026-03-22
+reopened_on:                 # comma-separated list, e.g. 2026-02-01, 2026-04-10
+reopened_reason:             # comma-separated list, e.g. "Scope expanded", "Bug found post-release"
+docs: []                     # optional list of repo-relative documentation paths, e.g. ["README.md", "docs/API.md"]
+tasks:
+  - E##_S##_T##
+  - E##_S##_T##
+---
+
+# Story: <Title>
+
+As a [type of user], I want [goal] so that [reason/value].
+
+## Acceptance Criteria
+- [ ] <Verifiable criterion — specific enough for a tester to check without asking>
+
+## Definition of Done
+- [ ] <Concrete, testable criterion>
+- [ ] <Concrete, testable criterion>
+```
+
+### Task — `E##_S##_T##_<slug>.md`
+
+```markdown
+---
+id: E##_S##_T##
+story_id: E##_S##
+epic_id: E##
+title: <Title>
+status: Pending
+date_created: YYYY-MM-DD
+date_started:
+date_completed:
+dates_previously_completed:  # comma-separated list, e.g. 2026-01-15, 2026-03-22
+reopened_on:                 # comma-separated list, e.g. 2026-02-01, 2026-04-10
+reopened_reason:             # comma-separated list, e.g. "Scope expanded", "Bug found post-release"
+assigned_to: developer | tester | scrum-master
+docs: []                     # optional list of repo-relative documentation paths, e.g. ["README.md", "docs/API.md"]
+---
+
+# Task: <Title>
+
+## Description
+<What needs to be done and why.>
+
+## Prerequisites
+<List any actions the user must take outside agent scope before or during implementation (e.g. creating accounts, configuring OAuth, provisioning services). Leave blank if none. If prerequisites exist, the developer must create an `_INSTRUCTIONS.md` file at `project/instructions/<E##_S##_T##>_INSTRUCTIONS.md`.>
+
+## Acceptance Criteria
+- [ ] <Verifiable criterion>
+```
+
+---
+
+## Story Format Standards
+
+## Reopen Tracking Fields
+
+**`dates_previously_completed`, `reopened_on`, `reopened_reason`** — These fields are **only populated when a previously completed item is being reopened and modified**. Leave them blank on first-run items. Each value is a comma-separated list to support multiple reopen cycles.
+
+## Documentation Provenance Field
+
+**`docs`** — Optional YAML list of documentation files affected by the board item. Use repo-relative paths such as `README.md` or `docs/API.md`.
+
+- Purpose: lets documentation workflows such as `/doc` trace which board items most recently affected a documentation file.
+- Scope: may appear on epics, stories, or tasks.
+- Optionality: existing board files remain valid when `docs` is omitted.
+- Format: use a YAML list. Inline (`docs: ["README.md"]`) and expanded list styles are both valid.
+
+These rules apply to every story file written or amended by the **Scrum Master**. They are enforced at write time by `scripts/validate-story-format.sh`.
+
+### Acceptance Criteria (`## Acceptance Criteria`)
+
+- **Required** — the section must exist in every story file.
+- **Format-agnostic** — may be prose, a numbered list, or checkboxes (`- [ ]`). No structural requirement beyond the section being present.
+- **Owner: Scrum Master** writes the AC when creating or amending the story.
+
+### Definition of Done (`## Definition of Done`)
+
+- **Required** — the section must exist in every story file.
+- **Must use `- [ ]` checkboxes** — plain bullet points (`- text`) are **not** valid. Each criterion must be written as an unchecked checkbox so the Tester can tick it during verification.
+- **Owner: Scrum Master** writes the DoD checkboxes when creating or amending the story. **Tester** ticks each `- [ ]` to `- [x]` during the test run, before writing any `Passed` or `Passed with remarks` status.
+
+### Validation script
+
+Run `scripts/validate-story-format.sh <path-to-story-file>` to verify a story file meets these requirements. The script exits 0 on success and non-zero with a descriptive error message on failure.
+
+Run `scripts/validate-board.sh <path-to-board-file>` to validate epic, story, or task frontmatter keys. The helper accepts optional `docs` annotations and remains backward compatible with existing board files that omit `docs`.
+
+---
+
+## Linking Convention
+
+- Every story file must list its parent epic ID in the `epic_id` frontmatter field.
+- Every task file must list both `story_id` and `epic_id`.
+- Every epic file must list all of its constituent story IDs in the `stories` array.
+- Every story file must list all of its constituent task IDs in the `tasks` array.
+- These lists are the authoritative index. The scrum master maintains them; other agents must not modify them.
+
+---
+
+## File Locking (Concurrency Control)
+
+Before writing to any board file, agents must:
+
+1. Check for a `<filename>.lock` file adjacent to the target file.
+2. If the lock file exists and its modification time is less than 60 seconds ago — wait up to 10 seconds and retry once. If still locked, abort and write a problem rapport.
+3. If no lock exists (or it is stale, older than 60 seconds) — create the lock file, perform the write, then delete the lock file.
+4. Always delete the lock file in success and failure paths. Use a `trap` or equivalent cleanup.
+
+---
+
+## Rapport Types
+
+| Type                    | Used by            | Location                                        |
+|-------------------------|--------------------|-------------------------------------------------|
+| `conflict`              | developer          | `project/rapports/problems/`                    |
+| `implementation_blocker`| developer          | `project/rapports/problems/`                    |
+| `security_concern`      | developer          | `project/rapports/problems/`                    |
+| `test_failure`          | tester             | `project/rapports/problems/`                    |
+| `analysis`              | tester             | `project/rapports/analysis/`                    |
+
+---
+
+## Queue Trigger Types
+
+### `scrum_triggers.jsonl` — processed by scrum master at session start
+
+| Type             | Written by  | Purpose                                                |
+|------------------|-------------|--------------------------------------------------------|
+| `rapport_review` | on_session_end.sh | New problem rapport(s) detected; create backlog items or mark Failed |
+| `status_review`  | on_session_end.sh | Session ended; review board for stale statuses        |
+| `story_rollup`   | tester / on_session_end.sh | All tasks under story complete; check rollup |
+
+### `developer_triggers.jsonl` — processed by developer at session start
+
+| Type                     | Written by          | Purpose                                       |
+|--------------------------|---------------------|-----------------------------------------------|
+| `implementation_assignment` | on_session_end.sh (from scrum-master handoff) | New tasks ready for implementation |
+| `rework_assignment`      | on_session_end.sh (from tester handoff) | Tests failed; address rapport and re-implement |
+
+### `tester_triggers.jsonl` — processed by tester at session start
+
+| Type              | Written by          | Purpose                                         |
+|-------------------|---------------------|-------------------------------------------------|
+| `test_assignment` | on_session_end.sh (from developer handoff) | Implementation complete; run tests against worktree |
+
+### `.session_handoff.json` — transient, consumed by on_session_end.sh
+
+Written by an agent as the **last action** of its session. Consumed and deleted by `on_session_end.sh`. The file must not persist across sessions.
+
+| Field         | Required by          | Notes                                    |
+|---------------|----------------------|------------------------------------------|
+| `agent`       | all                  | `scrum-master`, `developer`, or `tester` |
+| `status`      | all                  | See per-agent values below               |
+| `session_id`  | all                  |                                          |
+| `task_ids`    | scrum-master only    | Array of task IDs assigned for implementation |
+| `task_id`     | developer, tester    | Single task ID                           |
+| `story_id`    | all                  |                                          |
+| `epic_id`     | all                  |                                          |
+| `worktree`    | developer, tester    | Absolute path                            |
+| `paths`       | developer, tester    | Commit SHAs                              |
+| `rapport_file`| tester only          | Path to rapport if status is failed/error |
+| `date`        | all                  | ISO 8601 UTC                             |
+
+**Status values per agent:**
+- `scrum-master`: `planning_complete`
+- `developer`: `implementation_complete`
+- `tester`: `passed`, `passed_with_remarks`, `failed`, `error`
+
+
+
+Located at `project/configs/workflow.json`. Scaffolded by `/init` and owned by the scrum master.
+
+```json
+{
+  "statuses": ["Pending", "In Progress", "Passed", "Passed with remarks", "Failed", "Rejected", "Blocked"],
+  "rapport_types": ["conflict", "implementation_blocker", "security_concern", "test_failure", "analysis"],
+  "paths": {
+    "board": "project/board",
+    "epics": "project/board/epics",
+    "stories": "project/board/stories",
+    "tasks": "project/board/tasks",
+    "instructions": "project/instructions",
+    "rapports_problems": "project/rapports/problems",
+    "rapports_analysis": "project/rapports/analysis",
+    "queue": "project/queue",
+    "logs": "project/logs",
+    "data": "project/data",
+    "configs": "project/configs",
+    "documentation": "project/documentation",
+    "documentation_plans": "project/documentation/plans",
+    "documentation_summaries": "project/documentation/summaries"
+  },
+  "agents": ["developer", "tester", "scrum-master"]
+}
+```

package/templates/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: skill-name
+description: One-line description of what this skill does
+keywords:
+  # Short words/phrases (1-3 words) strongly associated with this skill
+  # Example: - brainstorm
+examples:
+  # Natural-language prompts that should trigger this skill
+  # Example: - "let's plan a new feature"
+metadata:
+  prefered_agent: developer
+---
+
+## Instructions
+
+<!-- Describe the steps the agent should take when this skill is invoked. -->

package/templates/SKILL_TEMPLATE.md

@@ -0,0 +1,28 @@
+---
+name: <skill-name>
+description: <One-sentence description of what this skill does and when to use it.>
+metadata:
+  prefered_agent: <agent-name>   # optional — remove if not applicable
+---
+
+# <Skill Title> — <Short tagline>
+
+## Instructions
+
+### 1. <First step title>
+
+<Describe what to do in this step.>
+
+### 2. <Second step title>
+
+<Describe what to do in this step.>
+
+### Session End
+
+When this skill's session concludes, emit the following signal on its own line so the Jenga Router clears the active session:
+
+```
+[JENGA:SESSION_END:<skill-name>]
+```
+
+Replace `<skill-name>` with the actual skill name from the frontmatter.

package/templates/USER_INSTRUCTIONS_TEMPLATE.md

@@ -0,0 +1,22 @@
+# <Action Name> — Setup Instructions
+
+**Epic**: E## — <epic title>
+**Required before**: <story or task that depends on this>
+
+## Overview
+
+<Brief description of what the user needs to set up and why.>
+
+## Steps
+
+1. <Step one>
+2. <Step two>
+3. <Step three>
+
+## Verification
+
+<How the user can confirm the setup is complete and working.>
+
+## Notes
+
+<Any caveats, links to external docs, or environment-specific instructions.>

package/templates/copilot-instructions.md.tpl

@@ -0,0 +1,55 @@
+# GitHub Copilot Instructions
+
+This file configures GitHub Copilot's behavior for this project. The block between the Jenga markers is managed automatically by `jenga init` — do not edit it manually.
+
+<!-- JENGA:START -->
+## Jenga Agent Framework
+
+This project uses **Jenga** — a skill-based AI agent framework. Jenga organises project work into Epics, Stories, and Tasks managed on a scrum board. It routes user messages to specialised **skills** that execute defined workflows.
+
+### How Jenga Works
+
+- Each **skill** is a self-contained instruction set stored under `.agents/skills/<skill-name>/` (the non-Claude discovery path; Claude Code reads the same content from `.claude/skills/`).
+- Skills are invoked by typing `/skill-name` in the chat prompt.
+- The active project directory is available via the `JENGA_PROJECT_DIR` environment variable. **Use `JENGA_PROJECT_DIR` — not `CLAUDE_PROJECT_DIR` or any other agent-specific variable** — as the canonical path to the project folder.
+
+### Skill Routing
+
+When a user's message matches a known skill keyword or intent, invoke the skill immediately using the slash-command syntax:
+
+```
+/skill-name
+```
+
+Do **not** answer skill-related requests with free-form prose if a matching skill exists — delegate to the skill instead.
+
+For free-form questions (architecture, code review, debugging, general Q&A) that do not match a skill, answer directly using your full capabilities.
+
+#### Routing decision table
+
+| Situation | Action |
+|-----------|--------|
+| Message matches a skill keyword or intent | Invoke `/skill-name` |
+| Message is a general coding or project question | Answer directly |
+| Ambiguous — could be skill or free-form | Prefer the skill; mention it is being invoked |
+
+### Available Skills
+
+{{SKILL_LIST}}
+
+### Session End
+
+GitHub Copilot CLI does not fire a native session-end hook. To replicate the cleanup logic that Claude Code triggers via its `SessionEnd` hook, run the following script at the end of any Copilot session or after completing a significant skill (e.g. `commit`, `lgtm`):
+
+```bash
+bash "$(node -p "path.dirname(require.resolve('jenga-agent/package.json'))")/hooks/copilot_session_end.sh"
+```
+
+The `hooks/`, `lib/`, `scripts/`, `templates/`, and `mcp/` directories all live inside the installed `jenga-agent` package (`node_modules/jenga-agent/…`) — they are **not** copied into the project. The script above sources `lib/resolve-project-dir.sh` and delegates to `hooks/on_session_end.sh` (both from the same package), which handle queue routing, rapport detection, handoff file processing, and todo cleanup. See [`docs/hook-parity.md`](docs/hook-parity.md) for the full Claude Code ↔ Copilot hook parity reference.
+
+### Notes
+
+- Always resolve file paths relative to `JENGA_PROJECT_DIR`.
+- When a skill asks you to read a file such as `SKILL.md` or a task file, look for it inside `JENGA_PROJECT_DIR/.agents/skills/` or `JENGA_PROJECT_DIR/project/board/` respectively.
+- Commit messages and branch names follow the EST naming convention (`E<n>_S<n>_T<n>`).
+<!-- JENGA:END -->