@jenga-ai/agent 1.0.0

package/skills/do/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: do
+description: Execute tasks from the scrum board. Reads from project/todo.md, resolves each entry to its full scrum board context, and drives the developer agent through implementation with the correct sender object and communication contract. Loops until all selected tasks are done or the user exits.
+keywords:
+  - do
+  - execute
+  - implement
+  - work on
+  - build
+examples:
+  - "implement the login feature"
+  - "work on the API endpoint"
+metadata: 
+  prefered_agent: developer
+---
+
+# Do — Execute Scrum Board Tasks
+
+## Instructions
+
+### 1. Check for `project/todo.md`
+Run `bash scripts/todo_manager.sh exists`. If it exits non-zero, inform the user there are no queued tasks and exit.
+
+### 2. List tasks and let the user choose
+Run `bash scripts/todo_manager.sh list` to display the queued tasks. Ask the user:
+- Execute a specific task (by number or title)
+- Execute the next task from the top of the list
+- Exit
+
+### 3. Detect and break down Epics or Stories (scrum-master phase)
+
+Before resolving a task for execution, inspect the selected entry's ID:
+
+- **Epic (`E##`)** — the entry refers to a whole epic that has not yet been broken into stories.
+  Use the scrum-master agent to read the epic's board file (`$(bash scripts/board_resolver.sh)epics/`) and decompose it into stories. For each story produced:
+  1. Write a story file to `$(bash scripts/board_resolver.sh)stories/`.
+  2. Run `bash scripts/todo_manager.sh add '<story title>: <E##_S##>'`
+  After breakdown, Run `bash scripts/todo_manager.sh remove '<epic entry title>'` and go back to step 2 so the new stories are visible.
+
+- **Story (`E##_S##`) with no tasks** — the entry refers to a story that has not yet been broken into tasks.
+  Check `$(bash scripts/board_resolver.sh)tasks/` for any task files whose front-matter `story_id` matches this story. If none exist, use the scrum-master agent to read the story's board file and decompose it into tasks. For each task produced:
+  1. Write a task file to `$(bash scripts/board_resolver.sh)tasks/`.
+  After breakdown, keep the story entry in `project/todo.md` (tasks are discovered from it automatically). Go back to step 2.
+
+- **Story (`E##_S##`) with existing tasks**, or **Task (`E##_S##_T##`)** — no breakdown needed; proceed to step 4.
+
+### 4. Resolve the task to full scrum board context
+Each todo entry uses the format: `<mission title>: <E##_S##_T##>` (or `E##_S##` if no task ID).
+
+Before starting:
+1. Locate and read the matching file from `$(bash scripts/board_resolver.sh)tasks/` (or `$(bash scripts/board_resolver.sh)stories/` if story-level)
+2. If the file does not exist, warn the user and skip — do not proceed with a task that has no scrum board definition
+3. Present a brief summary of the task: title, acceptance criteria, parent story, parent epic
+
+### 5. Invoke the developer agent
+Pass the following to the developer agent:
+
+**Sender object**: Copy `assets/sender_template.json` and populate all known fields (session_id, task_id, story_id, epic_id, current ISO 8601 UTC date).
+
+**Context payload** (plain text alongside the sender object):
+- Full task/story file content (title, description, acceptance criteria)
+- Parent story and epic summaries (read from board files)
+- Any relevant context from `project/PROJECT_SUMMARY.md`
+
+The developer agent will:
+- Log the incoming sender object to `project/logs/events.json`
+- Create a worktree named `<E##_S##_T##-short-slug>`
+- Implement, commit at milestones, and invoke the tester agent
+- Return when the tester has verified the work
+
+### 6. Verify documentation
+After the developer completes the task, confirm the following documentation was written:
+- **Execution plan** — `project/documentation/plans/<E##_S##_T##>-plan.md` must exist (written by the developer before starting work)
+- **Execution summary** — `project/documentation/summaries/<E##_S##_T##>-summary.md` must exist (written by the developer before invoking the tester)
+
+If either file is missing, ask the developer to produce it before continuing.
+
+Additionally, if the completed work introduces user-facing changes, update `README.md` and `WARP.md` accordingly.
+
+### 7. After successful completion
+- Check for any `_INSTRUCTIONS.md` files in `$(bash scripts/board_resolver.sh)tasks/` whose ID matches the completed task. If found, present them to the user and explain that these actions must be completed before the feature will work correctly.
+- Invoke the `/commit` skill to commit the work (if not already committed by the developer)
+- Run `bash scripts/todo_manager.sh remove '<task title>'` to remove the completed task from `project/todo.md`
+- Run `bash scripts/todo_manager.sh teardown` to delete `project/todo.md` if it is now effectively empty
+
+### 8. Loop
+Go back to step 1.
+

package/skills/do/assets/sender_template.json

@@ -0,0 +1,12 @@
+{
+  "sender": {
+    "agent": "orchestrator",
+    "session_id": "",
+    "task_id": "",
+    "story_id": "",
+    "epic_id": "",
+    "date": "",
+    "paths": [],
+    "worktree": ""
+  }
+}

package/skills/doc/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: doc
+description: Generate or update a documentation file by resolving a target path to a clear documentation objective before writing.
+metadata:
+  prefered_agent: developer
+keywords:
+  - doc
+  - documentation
+  - write docs
+  - generate docs
+  - update docs
+examples:
+  - "/doc"
+  - "/doc docs/API.md"
+  - "generate documentation for the CLI"
+  - "update the contributing guide"
+---
+
+# Doc — Documentation Synthesis and Regeneration
+
+## Input Format
+
+```text
+/doc [target-path]
+```
+
+- If `target-path` is omitted, default to `README.md`.
+- If `target-path` is provided, use it exactly as written after `/doc`.
+- Do not guess additional arguments or rewrite the requested path.
+
+## Reference Asset
+
+Load `skills/doc/assets/path-objectives.yaml` before resolving the documentation objective. Treat it as the source of truth for the `default_target`, known target paths, and their structural requirements.
+
+## Synthesis Context Contract
+
+After target resolution, all generation must operate on a synthesis context object. E24_S03 is responsible for producing the final implementation, but this story defines the field contract that downstream generation must consume.
+
+```yaml
+target_path: README.md
+objective: project overview
+project_name: JengaAgent
+project_description: Structured multi-agent development workflow
+features: []
+getting_started: []
+board_items: []
+conflicts_resolved: []
+sources_used: []
+existing_intent: null
+```
+
+Required fields from E24_S03:
+- `target_path`
+- `objective`
+- `project_name`
+- `project_description`
+- `features`
+- `getting_started`
+- `board_items`
+- `conflicts_resolved`
+- `sources_used`
+- `existing_intent`
+
+If the shared collector from E24_S03 is not yet merged, construct a temporary context with the same field names so later steps remain compatible.
+
+## Instructions
+
+### 1. Parse the target path
+
+1. Read `default_target` from `skills/doc/assets/path-objectives.yaml`. If it is missing, fall back to `README.md`.
+2. Remove the `/doc` command token from the invocation.
+3. Trim the remaining text.
+4. If nothing remains, set `target_path` to `default_target`.
+5. Otherwise, set `target_path` to the trimmed remainder.
+
+Examples:
+- `/doc` → `target_path = README.md`
+- `/doc docs/API.md` → `target_path = docs/API.md`
+- `/doc docs/CLI.md` → `target_path = docs/CLI.md`
+
+### 2. Resolve the objective from the rule table
+
+1. Read `skills/doc/assets/path-objectives.yaml`.
+2. Find an entry whose `path` exactly matches `target_path`.
+3. If a match exists, set:
+   - `objective` to the entry's `objective`
+   - `objective_summary` to the entry's `summary`
+   - `required_sections` / `optional_sections` from the entry when present
+4. If no match exists, stop and use the ambiguity gate in Step 4.
+
+### 3. Surface the resolved contract before continuing
+
+Before any synthesis or writing work, clearly surface the resolved contract in this shape:
+
+```text
+Resolved /doc target
+- target_path: <target_path>
+- objective: <objective>
+- summary: <objective_summary>
+- required_sections: <required_sections when present>
+- optional_sections: <optional_sections when present>
+```
+
+If the matched rule includes section guidance, carry it forward as constraints for the subsequent documentation work.
+
+### 4. Ambiguity gate for unknown targets
+
+If `target_path` is not present in `skills/doc/assets/path-objectives.yaml`:
+
+- Ask the user exactly: `What should <target_path> document? Please describe the objective.`
+- Do **not** guess the objective.
+- Do **not** proceed with documentation generation or updates until the user answers.
+- Once the user clarifies, treat their response as the `objective`, set `objective_summary` from the same clarification when helpful, surface the resolved contract, and continue.
+
+### 5. Load or assemble the synthesis context
+
+1. Start from the E24_S03 synthesis context when it is available.
+2. Ensure `target_path` and `objective` from Steps 1–3 are copied into the context.
+3. Populate `project_name`, `project_description`, `features`, `getting_started`, `board_items`, `conflicts_resolved`, and `sources_used` from the evidence collector.
+4. If any field is temporarily unavailable because E24_S03 has not landed yet, gather the missing evidence manually and store it under the same field names.
+5. Initialise `existing_intent` to `null` before inspecting the target file.
+
+### 6. Read the existing target before generation
+
+`/doc` owns the full target file. If the target already exists:
+
+1. Read the current file before generating anything.
+2. Extract maintainer intent that may still matter after regeneration, such as:
+   - custom sections that still fit the target objective
+   - warnings, caveats, migration notes, or known-issue callouts
+   - terminology preferences or audience cues
+   - maintainers' explicit scope boundaries
+3. Do **not** carry forward stale factual claims that conflict with the new evidence.
+4. Save the retained intent into `synthesis_context.existing_intent`.
+
+If the target file does not exist, keep `existing_intent = null`.
+
+### 7. Generate a complete replacement file
+
+1. Build a **full file string** from the synthesis context and the resolved target objective.
+2. Treat the generated output as the entire authoritative file.
+3. Do **not** patch a single section, append new text to the end, or leave untouched legacy sections in place.
+4. Keep the output valid Markdown.
+5. When writing, replace the old file contents in one operation.
+
+### 8. Generate `README.md` for the project-overview objective
+
+When `target_path = README.md`, generate the full document around the resolved project-overview contract.
+
+#### Required structure
+
+```md
+# <project_name>
+
+## Description
+...
+
+## Getting Started
+...
+```
+
+#### Description rules
+
+- Source Description content from `project_description`, `features`, and any still-valid `existing_intent`.
+- Explain what the project is, what problem it solves, and who it is for.
+- Keep the section concise and factual.
+- Cap the section at **1000 words maximum**.
+- Prefer a tight narrative plus bullets over repetitive prose.
+
+#### Getting Started rules
+
+- Source the section from `getting_started` first.
+- Fill missing setup detail from concrete manifests and entrypoints already present in the codebase (for example `package.json`, `pyproject.toml`, `go.mod`, startup scripts, or checked-in app packages).
+- Cover install, configure, and run steps only when evidence exists.
+- Preserve useful setup warnings from `existing_intent` when they are still valid.
+- Output valid Markdown lists or numbered steps.
+
+### 9. Conditionally include a README Examples section
+
+Only add `## Examples` to `README.md` when the synthesis context supports a grounded project-type inference.
+
+#### Infer the project type from evidence
+
+Use the synthesis context first, then reinforce it with manifests and source layout:
+
+- **CLI** indicators:
+  - `bin` in `package.json`
+  - Python CLI entrypoints such as `[project.scripts]` / `[tool.poetry.scripts]`
+  - CLI-focused board items or feature descriptions
+  - command-oriented code or existing CLI docs
+- **API** indicators:
+  - web-framework dependencies
+  - route/controller files
+  - `openapi.yaml` / `openapi.yml`
+  - board items describing endpoints or request/response behavior
+- **Library / SDK** indicators:
+  - no CLI `bin`
+  - export-heavy modules or public interfaces
+  - registry-publishing metadata
+  - board items describing integration from another project
+
+Choose the strongest evidenced type in this priority order when multiple types appear: explicit synthesis-context evidence, manifest metadata, source-layout evidence, then board-item wording. If no type can be supported confidently, omit the Examples section entirely.
+
+#### Examples rules
+
+- Generate at least **two concrete examples** when the section is included.
+- Every example must come from real capabilities present in `features`, `getting_started`, `sources_used`, or retained `existing_intent`.
+- Match the example shape to the inferred type:
+  - **CLI** → command invocations with realistic flags and outcomes
+  - **API** → request/response examples such as `curl` or HTTP snippets
+  - **Library / SDK** → import-and-use code snippets
+- Do **not** include placeholder examples, pseudo-commands, or guessed endpoints.
+- If you cannot produce two grounded examples, omit the section instead of improvising.
+
+### 10. Generate non-README targets from the rule table
+
+For every known non-README target, the path-to-objective rule table determines the file structure. Generate a full document that satisfies the matched rule.
+
+#### `docs/API.md` — API reference documentation
+
+Required shape:
+
+```md
+# API Reference
+
+## Overview
+...
+
+## Endpoints or Interfaces
+### <module or route group>
+- Signature / method + path
+- Parameters or request fields
+- Return values or response shape
+
+## Request and Response Details
+...
+```
+
+Rules:
+- Group content by module, route family, or interface namespace.
+- Include function signatures or HTTP method/path pairs when evidence exists.
+- Document parameters, request bodies, return values, and notable errors.
+- Use `sources_used` and `board_items` to ground scope; do not invent undocumented endpoints.
+
+#### `docs/CLI.md` — CLI usage guide
+
+Required shape:
+
+```md
+# CLI Guide
+
+## Overview
+...
+
+## Commands
+...
+
+## Flags
+...
+
+## Examples
+...
+```
+
+Rules:
+- Derive the command name from CLI entrypoints such as `package.json#bin`.
+- List commands and subcommands with concise descriptions.
+- Document flags with names, accepted values, defaults, and effects when evidence exists.
+- Include usage examples grounded in real workflows from the synthesis context.
+
+#### `docs/CONTRIBUTING.md` — contributor guide
+
+Required shape:
+
+```md
+# Contributing
+
+## Development Setup
+...
+
+## Workflow
+...
+
+## Contribution Expectations
+...
+```
+
+Rules:
+- Use manifests, repo scripts, and existing maintainer guidance to describe setup.
+- Explain branch, PR, review, and testing expectations only from repository evidence.
+- Carry forward still-valid maintainer norms captured in `existing_intent`.
+
+#### `CHANGELOG.md` — changelog / release notes
+
+Required shape:
+
+```md
+# Changelog
+
+## <version or date heading>
+### Notable Changes
+- ...
+```
+
+Rules:
+- Derive entries from `git log`; do not fabricate releases.
+- Group entries by version tag when tags exist.
+- If version tags do not exist, group by date-based headings instead.
+- Summarize each entry from commit subjects and, when needed, nearby commit context.
+- Keep newest entries first.
+
+### 11. Continue using the resolved objective
+
+After the target path and objective are resolved, use them as the contract for all subsequent `/doc` work. Known paths must bypass the ambiguity gate, and all later decisions about evidence gathering, scope, regeneration, and structure must honor the surfaced `target_path` and `objective` instead of inferring a different goal.

package/skills/doc/assets/path-objectives.yaml

@@ -0,0 +1,38 @@
+default_target: README.md
+rules:
+  - path: README.md
+    objective: project overview
+    summary: Create or update a high-level project overview.
+    required_sections:
+      - Description
+      - Getting Started
+    optional_sections:
+      - Examples
+  - path: docs/API.md
+    objective: API reference documentation
+    summary: Document the public API surface, endpoints, inputs, outputs, and integration details.
+    required_sections:
+      - Overview
+      - Endpoints or Interfaces
+      - Request and Response Details
+  - path: docs/CLI.md
+    objective: CLI usage guide
+    summary: Explain command usage, arguments, flags, examples, and common workflows.
+    required_sections:
+      - Overview
+      - Commands
+      - Flags
+      - Examples
+  - path: docs/CONTRIBUTING.md
+    objective: contributor guide
+    summary: Explain how contributors should set up, work on, test, and submit changes.
+    required_sections:
+      - Development Setup
+      - Workflow
+      - Contribution Expectations
+  - path: CHANGELOG.md
+    objective: changelog / release notes
+    summary: Record notable changes, releases, and upgrade notes in chronological order.
+    required_sections:
+      - Release Entries
+      - Notable Changes

package/skills/doc-sync/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: doc-sync
+description: Compare the current state of a project with its documentation and update documentation to reflect changes. Accepts `update:`, `source:`, `exclude:`, and `minify:` arguments to control scope. Use when documentation may be out of date with implementation, or when the user asks to sync, refresh, update, or shrink docs.
+keywords:
+  - doc-sync
+  - documentation
+  - update docs
+  - sync docs
+examples:
+  - "update the documentation"
+  - "sync docs with current state"
+---
+
+# Doc-Sync — Keep Documentation in Sync with the Codebase
+
+## What this skill does
+
+Analyses project source files, compares them against existing documentation, and updates any documentation that is stale, incomplete, or missing. Can be scoped with arguments to focus on specific files or exclude noise.
+
+---
+
+## Argument Parsing
+
+Before doing anything, check the user's message for arguments. Arguments may appear in any order and may be combined in a single invocation.
+
+| Argument | Format | Meaning |
+|---|---|---|
+| `--update:` | `update: <path(s)>` | Documentation file(s) to check and update. Comma or space-separated. |
+| `--source:` | `source: <path(s)>` | Source file(s) or director(ies) to prioritize when analysing changes. Comma or space-separated. |
+| `--exclude:` | `exclude: <path(s)>` | File(s) or director(ies) to skip entirely — neither read as source nor updated. Comma or space-separated. |
+| `--minify:` | `minify: <percent>` | Reduce each target documentation file by approximately N% by removing redundant and non-essential content. Defaults to `70` (i.e. scale down to 70% of original size) if no value is given. |
+
+**Examples:**
+- `doc-sync update: docs/API.md source: src/api/`
+- `doc-sync exclude: node_modules, dist update: README.md`
+- `doc-sync source: src/auth/ update: docs/auth.md, docs/security.md`
+- `doc-sync minify: 50 update: docs/API.md`
+- `doc-sync minify: update: README.md` *(uses default 70%)*
+
+All paths are interpreted relative to the project root.
+
+---
+
+## Instructions
+
+### 1. Parse arguments
+
+Extract any `update:`, `source:`, `exclude:`, and `minify:` values from the user's message.
+- Store each as a list: `update_targets`, `source_paths`, `exclude_paths`.
+- Store `minify` as a number `minify_pct`. If the `minify:` key is present but has no value, default to `70`. If `minify:` is absent entirely, set `minify_pct` to `null` (no minification).
+- Merge `exclude_paths` with the default excludes from `assets/default_excludes.txt`.
+
+### 2. Resolve update targets
+
+If `update_targets` is **not empty**, use those paths as the documentation files to update.
+
+If `update_targets` is **empty**, resolve targets from `assets/doc_targets.md`:
+- Read the file and parse the **Documentation Targets** list.
+- Each entry is a relative path to a documentation file to keep up to date.
+- If no entry matches an existing file, skip it and note it as missing.
+
+If neither source has targets (no arguments and no doc_targets), scan the project for documentation files:
+- Look for `*.md`, `docs/`, `documentation/`, `project/documentation/`, `README*`, `CHANGELOG*`, `CONTRIBUTING*`.
+- Ask the user: *"I found the following documentation files. Which should I update?"* — present the list and let them select.
+
+### 3. Resolve analysis sources
+
+If `source_paths` is **not empty**, read those files and directories (recursively if directories).
+
+If `source_paths` is **empty**, infer sources from each update target:
+- Read the existing content of the documentation file.
+- Look for mentions of paths, module names, function names, or API routes that hint at what code it describes.
+- Use those hints to locate relevant source files in the project.
+- Fall back to a broad scan of common source directories (`src/`, `lib/`, `app/`, project root) if no hints are found.
+
+Apply `exclude_paths` at this step — skip any file or directory matching an excluded path.
+
+### 4. Analyse for drift
+
+For each update target and its resolved sources:
+
+1. **Read the documentation file** — understand what it currently claims (structure, API, config, behaviour, examples).
+2. **Read the source files** — extract the current reality (exported functions, routes, config keys, CLI flags, env vars, class names, etc.).
+3. **Compare** — identify:
+   - Sections that reference removed or renamed things.
+   - Missing documentation for new things added in source.
+   - Outdated examples, wrong flag names, stale code snippets.
+   - Incorrect or missing configuration keys/values.
+
+### 5. Report findings before updating
+
+Before making any writes, present a concise drift summary per file:
+
+```
+📄 docs/API.md
+  ✏️  /api/users route renamed to /api/members in source
+  ➕  New endpoint POST /api/invites not documented
+  🗑️  Reference to deprecated `--verbose` flag still present
+
+📄 README.md
+  ✏️  Setup instructions reference Node 16; project now requires Node 20
+  ➕  New environment variable DATABASE_URL not listed
+```
+
+Ask: *"Should I apply all updates, or skip any of these?"*
+
+### 6. Apply updates
+
+For each approved update:
+- Edit the documentation file in-place — preserve existing structure, tone, and formatting.
+- Replace stale references with accurate ones.
+- Add new sections or entries for undocumented items.
+- Remove or mark deprecated items with a note if full removal seems too aggressive (ask when uncertain).
+- Do not alter sections that appear unrelated to the analysed source files.
+
+### 6a. Minify (if `minify_pct` is set)
+
+After sync edits are applied (or if only minification was requested), reduce each target file to approximately `minify_pct`% of its current size:
+
+**What to remove — in priority order:**
+1. Duplicate explanations of the same concept said in multiple ways.
+2. Verbose prose that restates what a code example already shows clearly.
+3. Historical context, changelogs, or migration notes buried in reference docs.
+4. Filler phrases ("It is important to note that…", "As mentioned above…").
+5. Redundant examples where one concise example covers the same case as two or three longer ones — keep the most illustrative, remove the rest.
+6. Section headers with no meaningful content beneath them.
+
+**What to keep — never remove:**
+- All unique technical facts (function signatures, config keys, env vars, routes, types).
+- Code examples that demonstrate something not expressed in prose.
+- Warnings, caveats, and known limitations.
+- Installation and setup steps.
+
+**Process:**
+1. Calculate the current character count of the file.
+2. Target size = `current_size × (minify_pct / 100)`.
+3. Remove content following the priority list above until the file is at or below the target size.
+4. If the target cannot be reached without removing essential content, stop at the smallest safe size and note the actual reduction achieved.
+5. Do not rewrite or paraphrase kept content — only remove.
+
+### 7. Summarise changes
+
+After all writes are done, print a summary:
+
+```
+✅ Updated 3 documentation files:
+   - docs/API.md       (2 sections updated, 1 added)
+   - README.md         (setup instructions refreshed)
+   - docs/config.md    (3 new env vars added)
+
+🗜️  Minified 2 documentation files:
+   - docs/API.md       (4 200 → 2 940 chars, −30%)
+   - README.md         (3 100 → 2 170 chars, −30%)
+
+⚠️  Skipped 1 file (no matching sources found):
+   - docs/legacy.md
+```
+
+If nothing needed updating, print: `✅ Documentation is already in sync with the source.`
+If minification could not reach the target, note: `⚠️ docs/API.md reduced to X% (target was Y% — essential content limit reached).`
+
+---
+
+## Reference files
+
+- `assets/doc_targets.md` — Editable list of documentation files this skill checks by default.
+- `assets/default_excludes.txt` — Paths always excluded from source analysis unless overridden.

package/skills/doc-sync/assets/default_excludes.txt

@@ -0,0 +1,21 @@
+# Default Excludes
+# Paths listed here are never used as analysis sources.
+# One path per line. Supports directory names and file names.
+# Lines starting with # are ignored.
+
+node_modules
+dist
+build
+.git
+.cache
+coverage
+.next
+.nuxt
+out
+tmp
+temp
+*.lock
+*.log
+package-lock.json
+yarn.lock
+pnpm-lock.yaml

package/skills/doc-sync/assets/doc_targets.md

@@ -0,0 +1,14 @@
+# Documentation Targets
+
+List the relative paths (from the project root) to documentation files that `doc-sync` should check and update by default — when no `update:` argument is provided.
+
+Add one path per line inside the list below. Blank lines and lines starting with `#` are ignored.
+
+## Documentation Targets
+
+<!-- Add your project's documentation files here, one per line -->
+README.md
+<!-- docs/API.md -->
+<!-- docs/config.md -->
+<!-- CHANGELOG.md -->
+<!-- CONTRIBUTING.md -->