github-issue-builder 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kulovema2012
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# github-issue-builder
+
+An agent skill for **Claude Code** and **Codex**. It turns a rough idea (one line, a voice-note ramble, a screenshot, a half-written ticket) into a GitHub issue that an AI coding agent can pick up and finish without coming back with questions. That includes exactly which branch and folder (worktree) to work in, and where its pull request goes.
+
+## Install
+
+```bash
+npx github-issue-builder install            # both tools, user scope (~/.claude/skills and ~/.agents/skills)
+npx github-issue-builder install --only claude
+npx github-issue-builder install --scope project --project ./my-repo
+npx github-issue-builder verify             # check the installed copies match the package
+npx github-issue-builder uninstall          # removes the skill, keeping a backup
+```
+
+Add `--dry-run` to see what would change.
+
+**Updating.** Run `npx github-issue-builder@latest install` again. The installer:
+- backs up any existing copy to `~/.github-issue-builder-backups/` and replaces it, or says "already up to date";
+- removes old copies from `~/.codex/skills` (and from `$CODEX_HOME/skills`), so Codex doesn't load the skill twice. Pass `--keep-legacy` to leave them;
+- warns if your **claude.ai account** also has this skill (synced into `~/.claude/skills/synced/`). Only claude.ai can update that copy, so replace or delete it in claude.ai → Settings → Capabilities → Skills.
+
+`verify` fails while an outdated duplicate is still around. To file issues directly, the skill uses an authenticated [`gh`](https://cli.github.com/) CLI or a GitHub connector. Without one, it hands you the drafts to copy and paste.
+
+## Usage
+
+Ask your agent something like "make an issue for …", "write a ticket: …", or paste any raw idea meant for GitHub. The skill:
+
+1. **Captures the idea**: who has what problem, what change fixes it, and its type (feature, bug, improvement, chore, docs).
+2. **Looks at the repo**: README, agent docs, build and test commands, the default branch, duplicate issues and existing labels.
+3. **Asks up to 4 clarifying questions, in one round**, and only when the answer changes the issue. One of them is the question behind most disappointing features: *is this a one-off, or will there be more of them?*
+4. **Checks the size**: one issue, or an epic plus child issues with a dependency graph and a parallel build order.
+5. **Writes the draft**: summary, spec, out of scope, testable acceptance criteria (Given/When/Then only where needed), branch and worktree setup, a step-by-step plan with a check after each step, a test plan, and risks and open questions.
+6. **Delivers it**: files the issue with `gh` after you confirm, creates the epic branch for epics, and replaces the placeholders with real issue numbers.
+
+Branch conventions: single issues branch from the default branch. For an epic, the skill creates `epic/<n>-<slug>`, and each child branches from it in its own worktree (`../wt-<n>`). Child PRs merge into the epic branch, and the final epic PR closes every child issue together.
+
+## Tested
+
+The "one-off or pattern?" question came from real client feedback: a single "lifetime package" feature that should have been a reusable package system. It was kept only after a blind A/B test. Six raw ideas, including a bug and a chore as controls, were run twice through each version and judged without the judges knowing which version wrote which draft. The new version won 9 of 12 pairs.
+
+## License
+
+MIT

package/github-issue-builder.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// github-issue-builder: installs the github-issue-builder skill for Claude Code and Codex.
+//
+//   npx github-issue-builder install   [--scope user|project] [--project DIR] [--only claude|codex] [--dry-run] [--home DIR]
+//                                      [--keep-legacy] [--codex-home DIR]
+//   npx github-issue-builder verify    [--scope user|project] [--project DIR] [--only claude|codex] [--home DIR]
+//   npx github-issue-builder uninstall [--scope user|project] [--project DIR] [--only claude|codex] [--dry-run] [--home DIR]
+//
+// Claude Code reads skills from .claude/skills and Codex from .agents/skills. The skill is identical for both,
+// so the same folder is copied to each. An existing copy is moved to a timestamped backup before it is replaced.
+// Old copies in <codex home>/skills are backed up and removed too (--keep-legacy skips that), and copies synced
+// from a claude.ai account are reported, since only claude.ai can update them.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const NAME = 'github-issue-builder';
+const BUNDLE = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.join(BUNDLE, 'payload', NAME);
+const argv = process.argv.slice(2);
+const command = argv[0] === undefined || argv[0].startsWith('--') ? 'install' : argv[0];
+const hasFlag = (name) => argv.includes(name);
+const optionValue = (name) => {
+  const i = argv.indexOf(name);
+  return i === -1 ? undefined : argv[i + 1];
+};
+
+const DRY = hasFlag('--dry-run');
+const ONLY = optionValue('--only');
+const SCOPE = optionValue('--scope') ?? 'user';
+const HOME = path.resolve(optionValue('--home') ?? os.homedir());
+const ROOT = SCOPE === 'project' ? path.resolve(optionValue('--project') ?? process.cwd()) : HOME;
+const BACKUP_DIR = path.join(HOME, `.${NAME}-backups`, new Date().toISOString().replace(/[:.]/g, '-'));
+
+if (!['user', 'project'].includes(SCOPE)) fail(`--scope must be user or project, got ${SCOPE}`);
+if (ONLY && !['claude', 'codex'].includes(ONLY)) fail(`--only must be claude or codex, got ${ONLY}`);
+
+const KEEP_LEGACY = hasFlag('--keep-legacy');
+
+const TARGETS = [
+  { tool: 'Claude Code', key: 'claude', dir: path.join(ROOT, '.claude', 'skills', NAME) },
+  { tool: 'Codex', key: 'codex', dir: path.join(ROOT, '.agents', 'skills', NAME) },
+].filter((t) => !ONLY || t.key === ONLY);
+
+// Older Codex versions (and some setups) read skills from <codex home>/skills. A copy left there makes Codex load
+// the skill twice, old and new, so install and uninstall move it to the backup folder. Orca and other launchers
+// point CODEX_HOME somewhere else, so that home is checked too.
+function legacyCodexCopies() {
+  if (ONLY === 'claude') return [];
+  // With --home (e.g. a test sandbox) the real CODEX_HOME is ignored so nothing outside that home is touched.
+  const codexHome = optionValue('--codex-home') ?? (optionValue('--home') ? undefined : process.env.CODEX_HOME);
+  const homes = SCOPE === 'project'
+    ? [path.join(ROOT, '.codex')]
+    : [path.join(HOME, '.codex'), codexHome].filter(Boolean);
+  const seen = new Set();
+  return homes
+    .map((h) => path.join(path.resolve(h), 'skills', NAME))
+    .filter((d) => !seen.has(d.toLowerCase()) && seen.add(d.toLowerCase()) && exists(d));
+}
+
+// Skills added to a claude.ai account are synced into ~/.claude/skills/synced/<account>/<name>. Claude Code loads
+// them next to local skills, and the sync restores anything deleted locally, so they can only be reported.
+function syncedClaudeCopies() {
+  if (ONLY === 'codex' || SCOPE === 'project') return [];
+  const root = path.join(HOME, '.claude', 'skills', 'synced');
+  if (!exists(root)) return [];
+  return fs.readdirSync(root, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => path.join(root, e.name, NAME))
+    .filter((d) => exists(path.join(d, 'SKILL.md')));
+}
+
+function warnSynced(copies) {
+  for (const d of copies) {
+    console.log(`! claude.ai account copy found: ${d}`);
+    console.log('  Claude Code loads it alongside this install and the claude.ai sync restores it if deleted here.');
+    console.log(`  To finish updating, open claude.ai > Settings > Capabilities > Skills and replace or delete "${NAME}".`);
+  }
+}
+
+function fail(msg) {
+  console.error(`${NAME}: ${msg}`);
+  process.exit(1);
+}
+
+function listFiles(dir, base = dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === '__pycache__') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listFiles(full, base));
+    else out.push(path.relative(base, full));
+  }
+  return out.sort();
+}
+
+const digest = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+function exists(p) {
+  try {
+    fs.lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function backup(dest) {
+  // Keep the backup inside BACKUP_DIR even for folders outside ROOT (e.g. a CODEX_HOME under AppData).
+  let rel = path.relative(ROOT, dest);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) rel = path.join('_outside', dest.replace(/^[A-Za-z]:/, (d) => d[0]));
+  const to = path.join(BACKUP_DIR, rel);
+  if (DRY) return console.log(`  would back up ${dest} -> ${to}`);
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  const stat = fs.lstatSync(dest);
+  if (stat.isSymbolicLink()) {
+    // A link (e.g. a junction to a shared skills folder): remove only the link, never its target.
+    fs.writeFileSync(`${to}.link.txt`, fs.readlinkSync(dest));
+    fs.rmSync(dest, { recursive: false, force: true });
+  } else {
+    fs.cpSync(dest, to, { recursive: true });
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+  console.log(`  backed up existing copy to ${to}`);
+}
+
+function sameAsPackage(dir, files) {
+  try {
+    return fs.statSync(dir).isDirectory() &&
+      files.every((f) => exists(path.join(dir, f)) && digest(path.join(dir, f)) === digest(path.join(SRC, f)));
+  } catch {
+    return false; // e.g. a dangling link
+  }
+}
+
+function install() {
+  const files = listFiles(SRC);
+  console.log(`${DRY ? '[dry run] ' : ''}Installing ${NAME} (${SCOPE} scope, ${files.length} files)`);
+  for (const t of TARGETS) {
+    console.log(`- ${t.tool}: ${t.dir}`);
+    if (exists(t.dir)) {
+      if (sameAsPackage(t.dir, files)) {
+        console.log('  already up to date');
+        continue;
+      }
+      backup(t.dir);
+      if (!DRY) fs.cpSync(SRC, t.dir, { recursive: true });
+      console.log(`  ${DRY ? 'would update' : 'updated'} (the previous copy is in the backup above)`);
+      continue;
+    }
+    if (!DRY) fs.cpSync(SRC, t.dir, { recursive: true });
+    console.log(`  ${DRY ? 'would install' : 'installed'}`);
+  }
+  for (const d of legacyCodexCopies()) {
+    if (KEEP_LEGACY) {
+      console.log(`! old Codex copy left in place (--keep-legacy): ${d}`);
+      continue;
+    }
+    console.log(`- Old Codex copy: ${d}`);
+    backup(d);
+    console.log(`  ${DRY ? 'would remove' : 'removed'} so Codex loads only the new copy`);
+  }
+  warnSynced(syncedClaudeCopies());
+  if (!DRY) console.log(`Done. Restart Claude Code / Codex, then ask an agent to "make an issue for <idea>" or run \`${NAME} verify\`.`);
+}
+
+function verify() {
+  const files = listFiles(SRC);
+  let ok = true;
+  for (const t of TARGETS) {
+    const missing = files.filter((f) => !exists(path.join(t.dir, f)));
+    const changed = files.filter((f) => !missing.includes(f) && digest(path.join(t.dir, f)) !== digest(path.join(SRC, f)));
+    const good = missing.length === 0 && changed.length === 0;
+    ok &&= good;
+    console.log(`${good ? 'OK  ' : 'FAIL'} ${t.tool}: ${t.dir}`);
+    for (const f of missing) console.log(`       missing: ${f}`);
+    for (const f of changed) console.log(`       differs from package: ${f}`);
+  }
+  for (const d of legacyCodexCopies()) {
+    ok = false;
+    console.log(`FAIL old Codex copy still present (Codex loads it too): ${d} (run \`${NAME} install\` to remove it)`);
+  }
+  const synced = syncedClaudeCopies();
+  for (const d of synced) {
+    const current = sameAsPackage(d, listFiles(SRC));
+    if (!current) ok = false;
+    console.log(`${current ? 'OK  ' : 'FAIL'} claude.ai account copy ${current ? 'matches the package' : 'is an older version'}: ${d}`);
+  }
+  if (synced.some((d) => !sameAsPackage(d, listFiles(SRC)))) warnSynced(synced);
+  process.exit(ok ? 0 : 1);
+}
+
+function uninstall() {
+  for (const t of TARGETS) {
+    if (!exists(t.dir)) {
+      console.log(`- ${t.tool}: not installed`);
+      continue;
+    }
+    console.log(`- ${t.tool}: ${t.dir}`);
+    backup(t.dir);
+  }
+  if (!KEEP_LEGACY) {
+    for (const d of legacyCodexCopies()) {
+      console.log(`- Old Codex copy: ${d}`);
+      backup(d);
+    }
+  }
+  warnSynced(syncedClaudeCopies());
+  console.log(DRY ? '[dry run] nothing removed' : 'Removed. Backups are kept so nothing is lost.');
+}
+
+if (!fs.existsSync(path.join(SRC, 'SKILL.md'))) fail(`payload missing: ${SRC}`);
+const commands = { install, verify, uninstall };
+if (!Object.hasOwn(commands, command)) fail(`unknown command "${command}" (install | verify | uninstall)`);
+commands[command]();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "github-issue-builder",
+  "version": "1.0.0",
+  "description": "Agent skill for Claude Code and Codex: turn a rough feature or bug idea into an agent-ready GitHub issue (or epic + child issues) with spec, acceptance criteria, plan, test plan and branch/worktree setup",
+  "type": "module",
+  "bin": {
+    "github-issue-builder": "github-issue-builder.mjs"
+  },
+  "files": [
+    "github-issue-builder.mjs",
+    "payload/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "skill",
+    "agent-skills",
+    "github",
+    "github-issues",
+    "issue-template",
+    "git-worktree"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kulovema2012/github-issue-builder.git"
+  },
+  "homepage": "https://github.com/kulovema2012/github-issue-builder#readme",
+  "bugs": {
+    "url": "https://github.com/kulovema2012/github-issue-builder/issues"
+  }
+}

package/payload/github-issue-builder/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: "github-issue-builder"
+description: "Turn a rough feature/bug idea into a GitHub issue (or epic + child issues) with spec, acceptance criteria, agent-ready plan, test plan, and branch/worktree setup, then optionally file it. Use for 'make an issue', 'write a ticket', or any raw idea meant for GitHub."
+---
+
+# GitHub Issue Builder
+
+Take a rough idea (one line, a voice-note ramble, a screenshot, a half-written ticket) and turn it into a GitHub issue that an AI coding agent (Codex, Claude Code) can pick up and finish without coming back with questions — including exactly which branch and folder (worktree) to work in, and where its pull request goes.
+
+The issue is always written in **English**, in plain, easy-to-read language. Short sentences. No clever or cryptic phrasing. The reader may be an agent with no memory of the conversation, so everything it needs must be in the issue itself.
+
+## Workflow
+
+1. Capture the idea
+2. Look at the repo (when one is reachable)
+3. Ask 2-4 clarifying questions (only if needed)
+4. Check the size — one issue or an epic with child issues?
+5. Write the draft(s)
+6. Show the draft, then create it on GitHub (issues + epic branch) or hand it over for copy-paste
+
+### 1. Capture the idea
+
+Restate the idea to yourself as: *who* has *what problem*, and *what change* fixes it. Decide the type: `feature`, `bug`, `improvement`, `chore`, or `docs`. A bug needs different information (steps to reproduce, expected vs actual) than a feature does.
+
+### 2. Look at the repo
+
+A plan that names real files and real test commands is far more useful to an agent than a generic one, so check for repo context before writing:
+
+- If the user named a repo or the working directory is a git repo: read the README, the top-level layout, contributing/agent docs (`CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md`), the package/build file to learn the test and lint commands, and grep for the code areas the idea touches.
+- If `gh` is available and authenticated: `gh repo view <repo> --json defaultBranchRef` gives the default branch name (don't assume `main`), `gh issue list --search "<keywords>"` spots duplicates, and `gh label list` shows which labels exist.
+- Keep this quick — you are looking for the files, patterns and commands the plan should point at, not reviewing the codebase.
+
+If no repo is reachable, continue without it, assume the default branch is `main`, and mark any file paths in the plan as guesses (see the writing rules).
+
+If you find an existing issue that already covers the idea, tell the user and ask whether to update that one instead of creating a duplicate.
+
+### 3. Ask clarifying questions
+
+Only ask when the answer would change the issue. Ask **at most 4** questions, in one round, using the multiple-choice question tool when available (offer concrete options, recommended one first). Good targets:
+
+- **Who and why** — who uses this, and what problem it solves (if the idea only states a solution)
+- **Scope edges** — which obvious neighbouring features are in or out
+- **What "done" looks like** — the one behaviour that must work for the user to be happy
+- **One-off or pattern** — when the request names a single instance of something that usually comes in plurals (one package, one plan, one report, one role), ask whether it stays the only one or more are coming. The answer decides between a one-off and a small reusable version, such as packages kept in a list an admin can add to. This is the most common reason a finished feature disappoints ("but I wanted more than one"), so ask it whenever it applies and the request doesn't already answer it.
+- **Hard constraints** — must not break X, must use library Y, deadline, platform
+- For bugs: steps to reproduce, expected vs actual result, environment
+
+Do not ask about things you can decide sensibly yourself (naming, file layout, which test framework the repo already uses). Do not ask about things the repo already answers.
+
+If the idea is already clear, skip this step. If the user is not around to answer, pick the most reasonable reading, and list each assumption under *Risks & open questions* so a human can correct it. Put an unanswered one-off-or-pattern question first there, phrased so it can be answered in one word, because it changes the scope more than anything else.
+
+### 4. Check the size
+
+An issue is too big when any of these is true:
+
+- It contains several deliverables that could ship and be reviewed separately
+- The plan would need more than about 8 steps
+- It touches several unrelated parts of the system (e.g. new DB schema + new admin UI + public API + billing)
+- An agent would likely need more than one focused session / one reasonably sized PR
+
+When it is too big, **propose a split** before writing: one epic issue plus child issues that each deliver one working, testable slice. For each child, work out what it depends on:
+
+- **Depends on nothing** → can start as soon as the epic branch exists
+- **Depends on another child** → must wait until that child is merged into the epic branch
+- Children with no dependency on each other can be built **in parallel**, each in its own worktree
+
+Show the proposed split as a short list with the dependencies and the build order (which children can run in parallel), and let the user confirm or adjust it. Then write the epic and every child with the templates below.
+
+### 5. Write the draft
+
+Use the templates in the next sections. Then reread each draft as if you were the agent that has to implement it with nothing else to go on: Is anything ambiguous? Could two people read a criterion and disagree about whether it passes? Is it clear which branch to start from and where the PR goes? Fix those spots before showing it.
+
+Issue numbers don't exist until the issues are created, so in the draft use placeholders such as `#<epic>` and `#<data-model>` and name branches with a slug only (e.g. `epic/<epic>-order-export`). Replace them with real numbers after creation (step 6).
+
+### 6. Deliver
+
+Show the full draft(s) (title + body) to the user in Markdown code blocks so they are easy to copy. Then:
+
+**If you can create issues** (an authenticated `gh` CLI, or a GitHub connector/MCP tool), ask "Create this on `<owner/repo>`?" and confirm the repo. On yes:
+
+*Single issue*
+1. Write the body to a file and run `gh issue create --repo <owner/repo> --title "<title>" --body-file <file>` (a body file avoids shell-escaping problems with backticks and quotes).
+2. Replace the `<n>` placeholders in its Branch & worktree section with the real number (`gh issue edit <n> --body-file <file>`).
+3. Don't create the working branch — the agent creates it from the latest default branch when it starts.
+
+*Epic + children*
+1. Create the epic issue first, then each child issue with `Part of #<epic>` at the top of its body.
+2. Create the **epic branch** on GitHub from the default branch — this is the only branch the skill creates:
+   ```
+   SHA=$(gh api repos/<owner>/<repo>/git/ref/heads/<default-branch> --jq .object.sha)
+   gh api repos/<owner>/<repo>/git/refs -f ref=refs/heads/epic/<epic>-<slug> -f sha="$SHA"
+   ```
+3. Edit every issue body so all placeholders become real issue numbers and real branch names (epic child list, `Depends on #…`, branch names, the final `Closes …` line).
+4. **Don't create the child branches or worktrees.** Each agent creates its own when it starts, from the latest epic branch. If they were created now, later children would miss the code merged by earlier ones.
+
+For both: only add labels that already exist in the repo (`gh label list`); mention any suggested label that doesn't exist instead of creating it. Reply with the created issue URL(s), the epic branch name, and which child issue(s) can start right away.
+
+**If you cannot create issues** (no `gh`, not authenticated, no connector): hand over the drafts as copy-paste text, plus the one command to create the epic branch if there is one, and say in one line what would let you file them directly next time (e.g. "run `gh auth login`" or connecting GitHub).
+
+Never create an issue or branch without the user's go-ahead — once created it is visible to everyone on that repo.
+
+## Branch and worktree conventions
+
+These keep every agent's work separated and make the flow predictable. Use them unless the repo already has its own convention (check `CONTRIBUTING.md` and recent branch names) — then follow the repo.
+
+| Thing | Name | Created by | Starts from | Merges into |
+|---|---|---|---|---|
+| Single issue branch | `<n>-<short-slug>` | the agent, when it starts | default branch | default branch |
+| Epic branch | `epic/<epic>-<short-slug>` | this skill, when filing | default branch | default branch (once, at the end) |
+| Child issue branch | `<n>-<short-slug>` | the agent, when it starts | latest epic branch | epic branch |
+| Worktree folder | `../wt-<n>` (next to the repo folder) | the agent, when it starts | — | removed after merge |
+
+Why an epic branch: all children share one goal, so their work collects in one place and the default branch never gets a half-built feature. Children with no dependency on each other can run in parallel in separate worktrees.
+
+Important GitHub behaviour to reflect in the issues: `Closes #n` in a PR only auto-closes the issue when the PR merges into the **default** branch. Child PRs merge into the epic branch, so their issues stay open. The final epic → default-branch PR must list `Closes #<child1>, #<child2>, …, #<epic>` so they all close together.
+
+## Issue template (single issue or child issue)
+
+**Title:** a short imperative sentence under ~70 characters that says what changes, e.g. `Add CSV export to the orders table`. If the repo's existing issues use a prefix style (like `feat:` or `[Bug]`), follow it.
+
+**Body:**
+
+```markdown
+<Child issues only: first line> Part of #<epic>
+
+## Summary
+<2-4 sentences: who has what problem, and what this issue changes to fix it. A reader should understand the point from this section alone.>
+
+## Background
+<Optional. Links, related issues, current behaviour, screenshots, why now. Delete the section if there is nothing useful to say.>
+
+## Spec
+<What the finished change does, described as behaviour, not code. Cover what applies:>
+- **User-facing behaviour:** what the user sees and does, step by step
+- **Inputs / outputs:** fields, formats, limits, defaults
+- **Data / API changes:** new endpoints, schema or config changes, migrations
+- **Edge cases:** empty state, errors, permissions, large inputs, concurrency
+- **Constraints:** things that must not change or break
+
+## Out of scope
+- <Things someone might reasonably expect this issue to do, that it deliberately does not do. Each one short. Point to a follow-up issue if one exists.>
+
+## Acceptance criteria
+- [ ] <One observable, testable behaviour per line.>
+- [ ] <...>
+
+**Key scenarios**
+<Only for the behaviours that are tricky or easy to get wrong — usually 1-3. Skip this sub-section if none.>
+
+**Scenario: <name>**
+- **Given** <starting state>
+- **When** <action>
+- **Then** <observable result>
+
+## Branch & worktree
+- **Depends on:** <#n — do not start until it is merged into the epic branch> / <nothing — can start now>
+- **Start from:** `<epic/<epic>-<slug>` for a child | `<default-branch>` for a single issue>
+- **Your branch:** `<n>-<slug>`
+- **Set up (run from the repo folder):**
+  ```
+  git fetch origin
+  git worktree add ../wt-<n> -b <n>-<slug> origin/<start-from branch>
+  cd ../wt-<n>
+  ```
+- **Open your pull request into:** `<epic branch for a child | default branch for a single issue>` — <child: "not into <default-branch>">
+- **PR description:** <child: "Part of #<epic>. Implements #<n>." | single issue: "Closes #<n>">
+- **After merge:** `git worktree remove ../wt-<n>` and delete the branch `<n>-<slug>`
+
+## Implementation plan
+<Ordered, small steps an AI coding agent can follow one at a time. Each step leaves the project building and its tests passing.>
+
+1. **<Step goal>**
+   - Files: `<path>` <mark `(verify)` if not confirmed in the repo>
+   - Do: <what to change, in a sentence or two>
+   - Check: `<command to run>` / <what to confirm>
+2. ...
+
+**Notes for the implementer**
+- Commands: install `<...>`, test `<...>`, lint `<...>`
+- Follow the existing pattern in `<file>` for <...>
+- Do not <constraint, e.g. change the public API of X>
+
+## Test plan
+- **Unit:** <what to cover>
+- **Integration / end-to-end:** <what to cover, if relevant>
+- **Manual check:** <short steps a human can do to see it working>
+
+## Risks & open questions
+- <Unknowns, risky parts, decisions still pending, and any assumptions made while writing this issue.>
+```
+
+For a **bug**, add a `## Bug details` section right after Summary with *Steps to reproduce*, *Expected result*, *Actual result*, and *Environment* (version, OS/browser, logs). The first acceptance criterion should be "the steps to reproduce no longer produce the bug", and the plan should start by writing a failing test that reproduces it.
+
+## Epic template
+
+```markdown
+## Summary
+<The overall goal, who it's for, and why it's split into several issues.>
+
+## Spec
+<High-level behaviour of the finished feature. Details live in the child issues.>
+
+## Out of scope
+- <...>
+
+## Acceptance criteria (whole feature)
+- [ ] <End-to-end behaviours that are only true once all children are merged.>
+
+## Epic branch
+- Branch: `epic/<epic>-<slug>` — created from `<default-branch>`
+- Every child issue branches from this epic branch and opens its PR into it.
+- `<default-branch>` is not touched until the final merge below.
+
+## Child issues (build order)
+| Issue | What it delivers | Depends on | Can run in parallel with |
+|---|---|---|---|
+| #<a> | <...> | — | — |
+| #<b> | <...> | #<a> | #<c> |
+| #<c> | <...> | #<a> | #<b> |
+
+- [ ] #<a> <title>
+- [ ] #<b> <title>
+- [ ] #<c> <title>
+
+## Keeping the epic branch up to date
+If `<default-branch>` gets other changes while this epic is in progress, merge it into the epic branch every few days so the final merge stays small:
+```
+git fetch origin
+git switch epic/<epic>-<slug>
+git merge origin/<default-branch>
+git push
+```
+
+## Finishing the epic
+- [ ] All child PRs merged into `epic/<epic>-<slug>`
+- [ ] Whole-feature acceptance criteria above pass on the epic branch
+- [ ] Open the final PR: `epic/<epic>-<slug>` → `<default-branch>`, with this description line: `Closes #<a>, #<b>, #<c>, #<epic>`
+- [ ] After it merges, delete the branch `epic/<epic>-<slug>`
+
+## Risks & open questions
+- <...>
+```
+
+## Writing rules
+
+**Acceptance criteria**
+- Describe *what* is observable, not *how* it is built. "Clicking Export downloads a CSV with one row per visible order" — not "add an `exportCsv()` function".
+- One behaviour per line, specific enough that two people would agree whether it passes. Replace words like "fast", "user-friendly", "properly" with something measurable or remove them.
+- Include the unhappy paths that matter: errors, empty data, missing permissions, invalid input.
+- Use Given/When/Then only where a checklist line would be ambiguous (multi-step flows, state-dependent behaviour, tricky edge cases). Most criteria should stay as plain checklist items.
+- Aim for roughly 4-10 criteria. More than ~12 is usually a sign the issue should be split.
+
+**Implementation plan (for AI agents)**
+- Order steps so each one can be finished, built, and tested before the next — e.g. data model → logic → API → UI → docs. An agent works best with small verified steps rather than one big change.
+- Name real files and real commands when you have seen them in the repo. When you haven't, still suggest the likely location but add `(verify)` so the agent checks before editing — an agent will trust a confident wrong path.
+- Each step gets a concrete *Check*: a test command, a build, or a specific thing to observe.
+- Tell the agent which existing code to copy patterns from; it keeps the change consistent with the codebase.
+- Keep steps to what the issue needs. Don't add refactors, extra features, or "nice to have" steps — put those under Out of scope or Risks.
+
+**Branch & worktree section**
+- Always present, in every single and child issue. Say plainly where the PR goes; for child issues add "not into `<default-branch>`", because opening the PR against the default branch is the most common mistake.
+- If the issue depends on another, say so in the first line so an agent doesn't start too early.
+
+**General**
+- Don't invent facts about the repo, the users, or the business. If something is unknown, say so under *Risks & open questions*.
+- Keep the issue self-contained. Summarise anything important from the conversation instead of writing "as discussed".
+- Delete template sections that truly don't apply rather than filling them with "N/A" — except Out of scope, Acceptance criteria, Branch & worktree, Test plan, and Risks & open questions, which are always present (write "None known" in Risks if that is true).
+
+## Example
+
+**Input idea:** "users should be able to export their orders to excel"
+
+After a quick repo look (React frontend in `web/`, Express API in `api/`, orders page at `web/src/pages/Orders.tsx`), good questions would be: *Which orders — all, or only the current filtered view? CSV or real .xlsx? Who can export — every user or admins only?* Suppose the answers are: current filtered view, CSV is fine, any logged-in user.
+
+This fits in one issue, so no epic. **Title:** `Add CSV export of the filtered orders list`
+
+**Sample acceptance criteria:**
+- [ ] The Orders page shows an **Export CSV** button to any logged-in user
+- [ ] Clicking it downloads `orders-YYYY-MM-DD.csv` containing exactly the orders matching the current filters
+- [ ] The CSV has a header row and the columns: Order ID, Date, Customer, Status, Total
+- [ ] With no matching orders, the button is disabled and shows a tooltip "No orders to export"
+- [ ] Exporting 10,000 orders completes without the page freezing
+
+**Sample out of scope:** Excel (.xlsx) format; scheduled or emailed exports; exporting order line items.
+
+**Sample Branch & worktree (after the issue was created as #57):**
+- Depends on: nothing — can start now
+- Start from: `main`
+- Your branch: `57-orders-csv-export`
+- Set up: `git fetch origin && git worktree add ../wt-57 -b 57-orders-csv-export origin/main && cd ../wt-57`
+- Open your pull request into: `main`
+- PR description: `Closes #57`
+- After merge: `git worktree remove ../wt-57` and delete the branch