Juscribe

View saved version →

---
name: hard-rules
description: Non-negotiable behavioral guardrails for Juscribe work — every-ticket lifecycle, COMMIT-IMMEDIATELY rule, no lint/test suppression, stakeholder-verbatim ticket descriptions (agent additions kept current), no false deliveries, external blockers when waiting on user input, where a new ticket gets filed, splitting a ticket blocked on a third party, steps-as-subtasks, no `git push`, and the document-discoveries protocol. Auto-invoke before committing, before editing a ticket description, before transitioning to finished/delivered, before filing or placing a new ticket, when work turns out to depend on someone outside the team, and on hitting an unfamiliar error or workaround. In a Juscribe-wired project, generic ticket and board language means Juscribe by default, unless the wording names another system (a PR, a GitHub issue, another tracker's key).
allowed-tools: Bash(jus *), Bash(git *), Read, Grep, Glob, Edit, Write
license: MIT
---

# Hard Rules — Non-Negotiable Behavioral Guardrails

> Read this first, every session. These rules are always on. They have been flagged repeatedly because violating them wastes time, ships broken work, or destroys the stakeholder's intent. The companion `ticket-workflow` skill covers the _how_ (the full lifecycle plus estimation, labels, testing gates, and the `jus` API reference); this skill covers the **must / must-not** that overrides it.

> **Prerequisite:** this SOP runs on the `jus` CLI, which the bundle does **not** install (`brew install juscribe/tap/jus` + `jus login`/`jus init`). If a `jus` command reports `command not found`, `No token available` or `No Juscribe project found`, the CLI is missing, unauthenticated or run from outside the project — **surface the one-line setup step and stop; do not loop `jus` commands against an unconfigured CLI.** See `ticket-workflow/references/setup.md`. **No shell, but Juscribe's MCP tools connected** (a chat app)? Use the tools instead, as `ticket-workflow` → Phase 0 says, and never tell a chat user to install Homebrew or the CLI. The rules below still apply; the commit, lint, test and git ones do not.

> **Every rule here is stated in full.** Where a section ends in a `references/` file, that file holds the same rule at length — the reasons, the measured failures, the edge cases. Open it when the situation it names is in front of you. The hooks back some rules mechanically, in the nine coding tools that run them, but only where they are installed; everywhere else each rule is prompt-level only, which makes following this skill **more** important. Which rule each hook backs: [`references/enforcement.md`](references/enforcement.md).

## Core Principles

- **The Juscribe workspace is the single source of truth** for all project scope, tasks, and progress. There is no separate scope document, scratchpad, or planning file.
- **Every piece of work MUST have a ticket** — create it BEFORE writing code, however small or ad-hoc the request. The one exception is revising a ticket not yet accepted: keep adding commits under its number.
- **Every project or ticket needs a description and an effort estimate.** A sparse user-created ticket gets fleshed out at pickup — root cause or approach, acceptance criteria — through the description rules below.
- **Transition at the natural moment, not batched.** The board must reflect reality in real time.
- **NEVER transition to `accepted` or `rejected`** — only the stakeholder decides those. The one exception is a chat app on Juscribe's hosted connector: when the person explicitly asks, record their decision with `accept_ticket` or `reject_ticket`, never on your own judgement.

Full text: [`references/core.md`](references/core.md).

## Commit Rules — THE MOST IMPORTANT CATEGORY

- **COMMIT IMMEDIATELY after code changes.** code → lint → **COMMIT** → then everything else: self-review, comments, transitions, replying to the user. Typing a response with an uncommitted change? **Stop and commi

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 13 — file references are metadata, not package contents.

View saved version →

---
name: retrospective
description: How to run a retrospective on an iteration and hand it over as a self-contained HTML report with charts, then record it back on the board. Covers what to gather (the first-hand accounts first — the ticket comments that hold most of them — then the tickets, their activity and the board's timezone), the sections a retrospective owes and the ones it must stop writing, when in the day work actually happened, production health and standing technical debt, drawing conclusions rather than counting metrics, hand-authored inline-SVG charts that need no library and no network, verifying derived numbers before you publish, sending the report's own HTML to the board so the iteration's details pane can show it, and writing the record back as an iteration comment. Auto-invoke on "retrospective", "retro", "sprint review", "review the iteration", or any request to review or summarize what an iteration delivered.
allowed-tools: Bash(jus *), Bash(git *), Read, Grep, Glob, Write
license: MIT
---

# Retrospective — Review an Iteration and Publish the Report

> Read this when asked to retrospect on an iteration, sprint or cycle. It covers gathering, analysis, charts, verification, delivery and the write-back. The companion `ticket-workflow` skill covers the ticket lifecycle and the `jus` API; this skill assumes it and does not repeat it.

## What you produce: a report and a record

**Two artefacts, and they are not the same document.**

|  |  |
| --- | --- |
| **The report** | One self-contained HTML file. Charts, tables, the full analysis. This is what a person reads, and you send it to the board, which stores and serves it. |
| **The record** | A comment on the iteration carrying `context: "retrospective"` — a short lede, where the report is, and the follow-ups you are **suggesting**. This is what the board keeps, and what someone replies to. |

**The record is short on purpose.** Its job is that the iteration carries a durable trace and something to reply to. If you find yourself restating the analysis in it, stop — you are writing the report twice, and the second copy is the one that goes stale.

⚠️ **NEVER deliver only the record.** A retrospective that fits in a comment is one you did not actually do. The board renders comments as plain markdown with no embedded HTML, so every chart you drew is lost the moment you paste it there.

## Step 1 — Read the first-hand accounts FIRST, and look on the TICKETS

```
jus api GET '/workspaces/{ws}/iterations/{iteration}/comments'
```

**MCP:** no MCP tool reads an iteration's comments. Read the thread in the app, or ask the person to paste it.

That is the iteration's own thread. On most boards it is **empty, or holds only the records of previous retrospectives** — measured on one board, one comment across 196 iterations, and it was a retrospective record. Read it, then keep going. The testimony is real; it is written one level down.

```
jus api GET '/workspaces/{ws}/tickets?iteration_id={iteration}&per_page=200&include_markers=true&include_comments=true&include_label_objects=false'
```

**MCP:** `list_tickets` with `iteration_id` and `include_markers`, then `get_ticket` on each ticket for its comments: the list pages 50 at a time and carries none.

⚠️ **`include_comments=true` IS WHAT TURNS THE TICKET LIST INTO THE LOG.** Without it the same request returns comment *counts*, which is a measure of back-and-forth and not a word of what anyone said. Where a workflow asks for a comment when work starts and another when it is delivered, every ticket carries a first-hand account of itself — the plan, what it assumed, what turned out to be wrong. Measured on a 112-ticket iteration: **252 comments on 102 of the 112 tickets**, median 2,940 characters, **78 tickets carrying language about a retry, a wrong assumption or a reversal.**

⚠️ **DO NOT READ THE WHOLE CORPUS.** That same fetch was **793,576 characters — roughly 198,000 tokens**, arriving as one 1.03 MB payload in 0.

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: ticket-workflow
description: The single load-bearing Juscribe SOP skill — the full ticket lifecycle from pickup to delivery, plus estimation, ticket types, labels, metadata, testing gates, and the complete `jus` CLI / API reference in bundled files this skill points at. Use when working any ticket — picking one up, transitioning state, investigating, sizing, labeling, writing tests, running pre-commit gates, calling `jus api`, committing, self-reviewing, finishing, delivering, handling rejections, processing batches, or resolving dependency blockers. Auto-invoke whenever a ticket ID (`#N`) or "work on this ticket" / "pick up backlog" / "deliver" / "rejected" appears. In a project wired to Juscribe (a `.jus/` directory or the `jus` CLI), bare ticket language — `#42`, the board, the backlog, deliver — means Juscribe tickets by default, unless the wording names another system (a PR, a GitHub issue, another tracker's key), so this skill is the one to invoke for them.
allowed-tools: Bash(jus *), Bash(git *), Bash(make *), Bash(cd *), Read, Grep, Glob, Edit, Write
license: MIT
---

# Ticket Workflow — Juscribe Lifecycle SOP

> **This skill and `.jus/SOP.md` overlap deliberately.** `jus init` appends that file to your AI context so a project with no plugin still has an SOP. This skill covers the same lifecycle in more depth and is kept more current: where the two differ, this one wins.
>
> Read it when working any ticket. It is the **single load-bearing skill** for Juscribe work. This file is the order of the lifecycle and, at each step, the reference file to open before it. What each step requires sits in that file, and so do the `jus` API, estimation, types, dependencies, subtasks and conversion: none of it costs anything until you open it. The companion [`hard-rules`](#related-skills) skill carries the must/must-not. Harnesses that run the jus hooks enforce the worst of those deterministically; everywhere else they are prompt-level only.

The lifecycle, in one line:

```
(1) create or pick up → (2) start → (3) investigate → (3b) apply labels → (4) code → (5) commit → (6) self-review → (7) finish
```

**Finishing is your last transition.** Deliver only when a person asks for it; Phase 6 says why.

Every change goes through every phase, however small or ad-hoc. Transition at the natural moment, never in a batch, so the board shows reality. **NEVER transition to `accepted` or `rejected`** — only the stakeholder decides. The one exception is a chat app on Juscribe's hosted connector: when the person explicitly asks you to accept or reject a ticket, record their decision with `accept_ticket` or `reject_ticket`, and never on your own judgement.

## Phase 0: Prerequisites — the `jus` CLI must be installed and authenticated

This SOP drives the board through the **`jus` CLI**, which the bundle does not install: the user installs it from juscribe.ai, then `jus login` or `jus init` (which also sets the `{ws}` used throughout this skill). **When a `jus` command fails before it reaches the board, open [references/setup.md](references/setup.md).** A missing CLI, a missing token, a retired token and an unreachable server each have a different fix, and only one of them is a rotation. `jus doctor` checks that these skills loaded, which `jus whoami` cannot.

**Do not loop `jus` commands against an unconfigured CLI, or against a 401.** Surface the one setup step the error points to, and stop.

**No shell, but Juscribe's MCP tools are connected?** That is a chat app, or any AI tool with the Juscribe connector and no terminal. Use the tools: each recipe in these files is followed by an **MCP:** line naming the tool that does the same job, or saying none does and what to do instead. Every board rule here still applies. The commit, lint, test, branch and git steps do not, since there is no repository. **Never tell a chat user to install Homebrew or the CLI.**

## Each step, and the file to open before it

⚠️ **This file holds the order, not t

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 16 — file references are metadata, not package contents.