janissary 0.5.0 → 0.5.2

package/ai/guidelines/pull-request-automation.md

@@ -0,0 +1,98 @@
+# PR Automation
+
+Scripts in `scripts/pr-*.sh` automate the `ai/tasks/merge-change-to-master.md` workflow: package the current changes into a PR against `master` and **merge it once there are no conflicts and all checks pass**. They are executable and called directly (no `npm run` wrappers). They work both in a normal checkout and in a workspaced clone (an independent `git clone` of the root repo's `origin` remote, so `origin` already points at GitHub).
+
+## Quick Start
+
+From the repo (or a workspace clone) with changes ready to ship:
+
+```bash
+./scripts/pr-merge-to-master.sh "Extract formatting helpers"
+```
+
+This single command runs Steps 0–9 of the workflow:
+
+1. ✅ Verifies there are changes (`pr-check-changes.sh`)
+2. ✅ Runs the check gate (`pr-check-gate.sh`; warnings don't fail it; skip with `--no-check`)
+3. ✅ Creates a feature branch (`pr-create-branch.sh`; from the title, or reuses the current non-`master` branch)
+4. ✅ Commits with a single author — **no co-authors** (`pr-commit.sh`)
+5. ✅ Resolves the GitHub remote and pushes (`pr-resolve-remote.sh`, `pr-push-branch.sh`)
+6. ✅ Opens the PR (`pr-create-pr.sh`)
+7. ✅ Polls conflict status (`pr-check-mergeable.sh`)
+8. ✅ Waits for all checks to pass (`pr-wait-checks.sh`)
+9. ✅ Merges and deletes the branch (`pr-merge.sh`)
+10. ✅ Prints a final report
+
+It stops and leaves the PR open if the check gate is red, if the PR conflicts with `master` (resolve those with `pr-rebase.sh` — see Step 7 of `ai/tasks/merge-change-to-master.md`), or if a check fails.
+
+```bash
+# explicit branch, and --no-check to skip the gate for a pre-existing red tree:
+./scripts/pr-merge-to-master.sh "Modernize color notation" style/modern-colors --no-check
+```
+
+## Individual Scripts
+
+Each step is also a standalone script for finer control or manual conflict resolution.
+
+### `./scripts/pr-check-changes.sh`
+Print uncommitted changes and commits ahead of `master`. Exits non-zero when there is nothing to ship.
+
+### `./scripts/pr-check-gate.sh`
+Run the check gate. Only the hard checks run: typecheck, lint errors, tests, CSS. Advisory quality checks (complexity, duplication, dead code) are not part of this gate — they belong to the human end-of-work gate (`npm run check:full`). Exits non-zero only on a hard-check failure.
+
+### `./scripts/pr-create-branch.sh <branch>`
+Create and switch to a feature branch (`git checkout -b`). No-op if already on it.
+
+### `./scripts/pr-commit.sh "<subject>" "[body]"`
+Stage all changes and commit with a single author. Adds **no** `Co-Authored-By:` trailer.
+
+```bash
+./scripts/pr-commit.sh "Extract formatting helpers" "Moved flattenBuffer and helpers to a new module"
+```
+
+### `./scripts/pr-resolve-remote.sh`
+Read `origin`'s URL and print `OWNER_REPO`/`BRANCH`/`GH_URL` for `eval`.
+
+```bash
+eval "$(./scripts/pr-resolve-remote.sh)"
+```
+
+### `./scripts/pr-push-branch.sh <remote> <branch>`
+Push the branch to GitHub with upstream tracking.
+
+### `./scripts/pr-create-pr.sh <owner/repo> <branch> "<title>" "[body]"`
+Create the PR against `master`. Prints the PR URL.
+
+### `./scripts/pr-check-mergeable.sh <branch> <owner/repo>`
+Poll merge status (6 attempts, 2-second intervals). Prints `MERGEABLE`, `CONFLICTING`, or `UNKNOWN`.
+
+### `./scripts/pr-rebase.sh <remote> [branch]`
+Fetch `master`, rebase the branch onto it, re-run the check gate, and force-push when clean. Exit 0 = done, exit 2 = conflicts to resolve (resolve the listed files' markers, then re-run to continue), exit 1 = hard error.
+
+### `./scripts/pr-wait-checks.sh <branch> <owner/repo>`
+Block on `gh pr checks --watch` until every check finishes. Exits non-zero if any check fails. A PR with no checks configured counts as passed.
+
+### `./scripts/pr-merge.sh <branch> <owner/repo>`
+Merge the PR (merge commit) and delete the remote branch. Only run once mergeable and all checks pass.
+
+## How It Works
+
+### Workspace clone handling
+In a workspaced tab, `origin` already points at GitHub over HTTPS — the workspace is an independent `git clone` of the root repo's `origin` remote. `pr-resolve-remote.sh` just reads it directly; no remote detection is needed.
+
+### Authentication inside a sandboxed workspace
+`git push` and `gh` (`pr-create-pr.sh`, `pr-merge.sh`) authenticate via `GH_TOKEN`, injected into the sandboxed workspace's environment from `.janissary/github-token` (a scoped, user-provisioned fine-grained PAT — see README's "GitHub push/PR access"). The workspace clone's local `credential.helper` (`!gh auth git-credential`) picks up that same token for `git push`. Without a token configured, these scripts fail from inside a sandboxed workspace (SSH auth is unreachable there, and there's no other credential path in) but work as before outside a workspace or with sandboxing disabled.
+
+### No interactive prompts
+All scripts use non-interactive `git` and `gh` commands, so they run without approval prompts.
+
+### Error handling
+Scripts exit non-zero on failure (no changes, commit/push/PR failure, failing checks, conflicts), so the orchestrator can stop and report rather than merging a bad PR.
+
+## Troubleshooting
+
+### "gh: command not found"
+Scripts fall back to `/usr/local/opt/gh/bin/gh`. Otherwise check `which gh` and `gh auth status`.
+
+### Merge conflicts
+`pr-merge-to-master.sh` stops on `CONFLICTING` and leaves the PR open. Run `./scripts/pr-rebase.sh <remote> <branch>`; if it stops with exit 2, resolve the listed files' markers and re-run it until it exits 0. Then re-run `./scripts/pr-wait-checks.sh` and `./scripts/pr-merge.sh`.

package/ai/guidelines/strategies-for-readable-summaries.md

@@ -0,0 +1,27 @@
+Use this as a style guide when generating or editing summary content. The reader is intelligent and curious but not a specialist. They read to understand and decide — not to be impressed.
+
+- Use a grounded, conversational tone; avoid academic register or corporate-neutral language
+- Match formality to context; default neither to stiff nor casual
+- Take a clear point of view — vague or uncommitted writing feels hollow
+- Include mild hedging where accurate: "probably," "often," "in most cases"
+- Lead with the main point or finding in the first sentence — do not build to it
+- Do not open by restating the question, prompt, or document title
+- Use paragraph breaks for pacing as well as topic shifts
+- Write in prose when ideas connect naturally; reserve bullets for genuinely discrete items
+- Avoid formulaic structure: introduction → three points → conclusion
+- Do not close with a summary that simply restates what was just said
+- Mix short and long sentences to create natural rhythm
+- Prefer active voice; use passive only when intentional
+- It is acceptable to start sentences with: And, But, So, Because
+- Break grammar rules deliberately when it improves clarity or tone
+- Keep sentences scannable — one idea per sentence when precision matters
+- Use concrete, specific words instead of abstract or vague ones
+- Use contractions naturally: don't, it's, you're, we're
+- Remove filler phrases: "It's worth noting that," "In conclusion," "It's important to remember," "It goes without saying," "As we can see"
+- Prefer plain verbs: use instead of utilize, show instead of demonstrate, help instead of facilitate
+- Assume the reader is intelligent; do not over-explain basic concepts
+- Leave some tension unresolved when the topic genuinely warrants it — not everything 
+- Avoid self-announcing transitions: "Moving on to...," "Now let's discuss...," "Turning to the topic of..."
+- Connect ideas through logic and word choice, not structural signposting
+- Let paragraph endings do transition work naturally
+- Do not Restate the same point in slightly different words across paragraphs

package/ai/guidelines/user-documentation.md

@@ -0,0 +1,177 @@
+# Writing User Documentation
+
+Guidance for writing user-facing docs (`documentation/user-documentation/`) from the internal specs
+(`product/specs/`). Specs describe implementation and behavior for contributors; user documentation
+describes tasks and concepts for someone running the app who has never read the spec and never
+will. Don't just reformat a spec into a doc page — rewrite it for the reader's goal, and drop
+every internal detail that doesn't serve that goal (see "No implementation leakage" below). For
+sentence-level tone, see [[human-writing-guidelines]]; this document is about structure and
+content, not prose style. For docs aimed at contributors instead of end users, see
+[[developer-documentation]].
+
+## Organize by the Diátaxis framework
+
+Every doc page has exactly one job. Diátaxis (https://diataxis.fr) splits that job along two axes
+— action vs. cognition, and learning vs. working — into four types. Decide which one a page is
+*before* writing it, and don't mix jobs on one page:
+
+| Type | Answers | Reader is | Example for this app |
+|---|---|---|---|
+| **Tutorial** | "Teach me, step by step" | Learning, needs hand-holding | "Your first session with `janus`" |
+| **How-to guide** | "How do I do X?" | Already competent, has a goal | "How to run a workspaced agent" |
+| **Reference** | "What are the exact facts?" | Looking something up mid-task | Command syntax tables (flags, subcommands, defaults) |
+| **Explanation** | "Why does it work this way?" | Building a mental model | "How tab grouping works" |
+
+A single spec file often contains material for two or three of these — split it rather than
+publishing the spec verbatim. `scheduling.md`, for example, has reference material (the form
+table, the `schedule` command grammar) and explanation material (why entries are tab-scoped, how
+firing interacts with the scheduler tick); those belong on different pages, or at least under
+different headings a reader can skip between.
+
+## Lead with the goal, not the mechanism
+
+Put the most useful sentence first — what the reader can now do — not the background or the
+implementation detail that makes it possible. If someone searches "open a web page in a tab," the
+first line should be `open <url>` opens it, not a paragraph about the opener registry pattern.
+Move architecture and "why" content into an Explanation page or a clearly marked aside; don't make
+the reader wade through it to find the command.
+
+## Examples before exposition
+
+For a CLI/TUI app, readers reach for examples before prose. Every how-to and reference page should
+show a runnable command near the top — ideally the most common invocation — before explaining
+flags or edge cases. Build from simple to complex within a page: the bare command first, then one
+variant, then the edge cases and error messages last. Full flag-by-flag breakdowns belong in the
+reference table, not the lede.
+
+## Minimalism: support the task, don't teach everything
+
+Carroll's minimalist-instruction research (the basis for most modern task-based writing) found
+that shorter, action-first documentation beats comprehensive manuals on learning time, confidence,
+and error recovery — not despite leaving things out, but because of it. Apply it directly:
+
+- Let the reader start on a real task immediately; don't preface a how-to with paragraphs of setup
+  or background they didn't ask for.
+- Cut passive reading wherever an example or a short exercise can substitute for it. A worked
+  command the reader can run teaches faster than a paragraph describing what the command does.
+- Document error recovery, not just the happy path — what a mistake looks like and how to get back
+  on track is exactly the content a minimal-but-complete page needs (this repo's specs already list
+  verbatim error/usage messages for this reason; carry the messages, not the mechanism, into the
+  user doc — see "No implementation leakage" below).
+- Make each page self-contained. A reader landing on a how-to guide from search shouldn't need to
+  have read three other pages first to follow it; link to prerequisites rather than assuming them.
+
+## Progressive disclosure
+
+Give the reader just enough to complete the task in front of them, and defer the rest behind a
+link or a lower heading rather than inlining it:
+
+- An overview or how-to page states the common case first, then links out to reference detail
+  (the full flag table) and edge cases rather than front-loading all of it.
+- Limit disclosure to one layer deep per page. A reader who has to click through several nested
+  "see more" links to find the one flag they need has a worse experience than one long reference
+  page with clear headings — progressive disclosure organizes what's *primary* vs. *secondary*, it
+  doesn't hide information behind a maze.
+- This is the same instinct as Diátaxis's separation of how-to from reference: the how-to page
+  shows the one command that solves the reader's problem; the reference page is where every flag,
+  default, and variant lives for the reader who already knows they need it.
+
+## No implementation leakage
+
+User documentation is written for a reader who has never seen the codebase and never needs to.
+Strip everything that only makes sense to a contributor:
+
+- No file paths, function names, module names, or internal class names (`src/tab.ts`,
+  `flattenBuffer`, `TabManager.markUnread` — these belong in `product/specs/`, never in
+  `documentation/user-documentation/`).
+- No "why we implemented it this way" engineering trade-off discussion — that's explanation for
+  contributors, not users. A user-facing Explanation page answers "why does the app behave this
+  way from where I'm sitting," not "why did we choose this data structure."
+- Command names, flags, error messages, and observable behavior are the only things that survive
+  the rewrite from spec to user doc.
+
+## Conventions specific to this app's docs
+
+- **Monospace for anything typed or displayed**: commands, flags, file paths, tab labels, key
+  chords (`Ctrl+R`, not "control R").
+- **Consistent command-syntax notation**: `<angle brackets>` for a required argument the reader
+  supplies, `[square brackets]` for optional, `a|b` for mutually exclusive choices — matching how
+  the specs already write usage lines (e.g. `open [external] [page] <target>`).
+- **Name the actual error/usage message** a reader will see, verbatim, rather than paraphrasing
+  it — that's what they'll search for.
+- **Cross-link, don't duplicate.** When a concept is fully explained elsewhere (e.g. Tab grouping),
+  link to that page instead of re-explaining it inline.
+
+## Style rules (borrowed from the Google developer style guide)
+
+- Second person ("you"), active voice, present tense.
+- Put UI/tab elements in **bold**, code and commands in `code font`.
+- Sentence case for headings.
+- Put conditions before instructions ("If the workspace doesn't exist, ..." not the reverse).
+
+## Plain language and accessibility
+
+Plain language is an accessibility feature, not just a style preference — WCAG's guidance on
+reading level, unusual words, and abbreviations exists because unnecessarily complex writing
+excludes readers with cognitive disabilities, non-native speakers, and anyone skimming under time
+pressure. Concretely:
+
+- Short sentences, one idea per sentence. Prefer the common word over the fancier synonym.
+- Define or avoid jargon and abbreviations on first use — including this app's own vocabulary
+  (`ACP`, `harness`, `workspaced agent`) the first time a page mentions it.
+- Use descriptive, specific headings (`Close a page tab`, not `Closing`) — headings are how both
+  sighted skimmers and screen-reader users navigate a page, and vague ones fail both.
+- Every screenshot or diagram needs alt text that conveys the same information the image does, not
+  just a filename or "screenshot of the app."
+
+## Visuals: use them with intent
+
+A screenshot or short screen recording earns its place when it shows something genuinely visual
+(a layout, a zoom/pan interaction, a dialog's button arrangement) — not as decoration and not as a
+substitute for an instruction a sentence could give faster ("click **Save** in the top-right" beats
+a screenshot of an ordinary button).
+
+- Prefer a short, silent, loopable clip over a screenshot when the point is a *motion* or sequence
+  (e.g. zooming an image tab, dragging to pan) — a still can't show that.
+- Skip visuals for generic, expected UI (a standard confirmation dialog, a plain text input) — they
+  add maintenance cost without adding information.
+- Place a visual immediately after the text it illustrates, give it a caption, and keep it minimal
+  — crop to the relevant area rather than showing the whole app window.
+- Never use a screenshot in place of a code sample or command — those must stay as selectable,
+  copyable text.
+- A visual is one more thing that goes stale when the UI changes; budget for updating it under the
+  same "docs as code, same PR" rule as the surrounding text (see below).
+
+## Validate it against real readers
+
+Before treating a page as done, run the two cheap checks that catch most usability problems:
+
+- **Task-based check**: hand the page to someone who fits the target audience and watch whether
+  they can complete the task using only the page, without narrating or helping them.
+- **Paraphrase check**: ask them to explain a section back in their own words — a garbled paraphrase
+  means the writing, not the reader, needs work.
+
+Findability matters as much as the writing itself: a correct page nobody can locate might as well
+not exist. Give every page a heading and title that matches the phrase a reader would actually
+search for (task-first, not implementation-first — "close a page tab," not "page tab teardown"),
+and make sure the site's navigation and search surface it from the terms a newcomer would use, not
+just the internal name for the feature.
+
+## Treat docs as code
+
+User docs live in version control (`documentation/user-documentation/`) next to the code they describe, same
+as everything else in this repo:
+
+- A behavior change that lands in a PR should update the doc page in the same PR when the change
+  is user-visible — don't let docs drift from behavior. Stale docs that describe removed or changed
+  behavior are worse than no docs, since they actively mislead.
+- Prefer many small, focused pages over one large page per feature area — mirrors the file-size and
+  single-responsibility guidance in [[code-guidelines]].
+- Review doc changes the same way code changes are reviewed; a doc PR should be readable as a diff.
+
+## Deciding what to document, and when
+
+Not every spec needs a public page, and not all at once. Tier by audience reach: onboarding-critical
+content first, everyday features next, advanced/specialized features after that, and pure
+implementation detail (the kind aimed at contributors, not users) left out of
+`documentation/user-documentation/` entirely — that belongs in `product/specs/`, per [[developer-documentation]].

package/ai/personas/algorithm.md

@@ -0,0 +1,14 @@
+[//]: # opencode:google/gemini-3.1-flash-lite:default
+
+You are an algorithms monitor. You watch the transcript of one or more terminal agent tabs solving coding-interview / LeetCode-style problems, and you suggest the algorithmic technique that fits the problem at hand:
+
+- Name the pattern the problem is really asking for: two pointers, sliding window, binary search (including on the answer), BFS/DFS, backtracking, dynamic programming, greedy, union-find, topological sort, heap / priority queue, prefix sums, monotonic stack, trie, or the like
+- Point out the data structure that unlocks the intended complexity — a hash map for O(1) lookup, a set for seen-tracking, a deque for a sliding window, a heap for top-k
+- Flag when the current approach looks like it will exceed the expected time or space bounds, and suggest the standard technique that brings it down (e.g. memoizing overlapping subproblems, sorting to enable two pointers, hashing to drop a nested loop)
+- Note common edge cases the pattern is known for: empty input, single element, duplicates, integer overflow, cycles, negative numbers, off-by-one at the window/partition boundary
+
+Keep each suggestion to the technique and the intuition for why it fits — one or two sentences. Do not write the full solution; point toward the approach so the work stays theirs. If the current approach is already the right one, say nothing.
+
+You never run commands and never take action yourself. If there is nothing genuinely useful to add, respond with nothing at all — silence is better than noise.
+
+Never say anything negative about the user or their work — no criticism of their choices, skill, or pace. Phrase every suggestion positively: point toward the technique that helps rather than dwelling on what is inefficient. Say "a sliding window keeps this O(n) here", not "your nested loop is too slow".

package/ai/personas/assistant.md

@@ -0,0 +1,25 @@
+[//]: # opencode:opencode/deepseek-v4-flash-free:default
+
+You are a helpful pair-programming monitor. You watch the transcript of one or more terminal agent tabs and web page tabs, and help the user follow and advance the work at hand.
+
+What you do depends on the kind of input you just saw:
+
+- **Harness output** (an AI coding agent working on its own in a terminal tab): your top priority is to **summarize** what the AI has done, is doing, or is trying to do, so the user can follow along at a glance without reading the raw transcript. Always write the summary — never reply with a bare acknowledgment ("OK", "Got it", "Understood"), an empty message, or a restatement of the instruction. If harness output is present, a concrete summary of that output is the only acceptable response. Do not suggest actions the harness is already about to perform — it will take its own next steps. Never report on whether the agent is busy, idle, paused, or waiting (e.g. "paused in manual mode, likely waiting") — the monitor's view of the transcript is insufficient to judge run state, and guessing at it produces misleading noise. Stick to summarizing what the content of the transcript shows.
+- **Web page tab output**: your top priority is to **summarize** the content or state of the page for the user.
+- **User input**: your top priority is to make **suggestions**. Summaries may happen more often than suggestions — suggest only when you clear a high bar (see below).
+
+## Suggestions
+
+Only make **non-trivial, high-value** suggestions. A high-value suggestion adds non-obvious value, combines several commands into one, or moves the user toward their goal in a single step rather than many. Before you speak, ask whether the user would have arrived at the same idea on their own in the next few seconds — if so, stay silent.
+
+Ground every suggestion in the user's **apparent task** — what they are actually trying to accomplish — not in the mechanics of whichever harness or agent happens to be running it. A suggestion should hold up even if the user switched to a different tool tomorrow.
+
+- Point out a non-obvious next step, failure cause, or better path the user is unlikely to have seen
+- Offer a command that collapses multiple steps into one, or that gets to the goal more directly than the obvious sequence
+- Flag things the agent appears to have missed: an unsaved file, an unfinished rename, a forgotten cleanup
+
+Suggesting a common, obvious command is **low value** — do not do it. Prompting to run the tests, a linter, a build, `git status`, or any routine command the user already knows to run adds noise, not help. Withhold these entirely.
+
+You never run commands and never take action yourself. Keep suggestions short and specific to what you just saw. If there is nothing genuinely non-trivial to say, respond with nothing at all — silence is better than noise.
+
+Never say anything negative about the user or their work — no criticism of their choices, skill, or pace. Phrase every suggestion positively: point toward the helpful next step rather than dwelling on what went wrong. Say "running the linter would catch this quickly", not "you forgot to run the linter".

package/ai/personas/link-scout.md

@@ -0,0 +1,16 @@
+[//]: # claude:claude-sonnet-5:default
+[//]: # tools: web_search, web_fetch
+
+You are a link scout. You watch the transcript of one or more terminal agent tabs and surface related content that would help the work at hand:
+
+- Official documentation for a library, framework, API, or tool the work is using
+- A reference page for an error message, standard, or spec being wrestled with
+- A canonical guide or example for the technique the work is reaching for
+
+You can search the web and fetch pages. Use those tools to confirm a link is real, current, and points where you expect *before* offering it — don't rely on memory alone. Prefer canonical, long-lived addresses (a project's official docs domain, an RFC, a standard's home page). Never guess a URL or offer a link you have not verified resolves — a wrong link is worse than none. When a search or fetch turns up nothing genuinely relevant and reliable, say nothing.
+
+Deliver each link as a runnable command so the user can open it in a page tab. Format the command as `open <url>` (for example, `open https://playwright.dev/docs/intro`). One link per suggestion, the single most relevant one.
+
+You never run commands and never take action yourself. Keep the suggestion text short — name what the link is and why it helps. If there is nothing genuinely relevant and reliable to offer, respond with nothing at all — silence is better than noise.
+
+Never say anything negative about the user or their work — no criticism of their choices, knowledge, or pace. Phrase every suggestion positively: point toward the helpful resource rather than what they seem not to know. Say "the Playwright locator docs cover this pattern well", not "you clearly don't know how locators work".

package/ai/personas/researcher.md

@@ -0,0 +1,12 @@
+[//]: # opencode:google/gemini-3.1-flash-lite:default
+
+You are a research monitor. You watch the transcript of one or more browsing, search, or reading tabs and help the investigation stay on track:
+
+- Notice when the same question keeps getting re-asked and point back to where it was already answered
+- Flag a promising thread that was opened and then dropped before it paid off
+- Call out when a new source contradicts something an earlier source established
+- Suggest a concrete next query, or the earlier source worth revisiting, when the search seems to be circling
+
+You never run commands, open pages, or take action yourself. Keep suggestions short and specific to what you just saw. If there is nothing genuinely useful to say, respond with nothing at all — silence is better than noise.
+
+Never say anything negative about the user or their work — no criticism of their choices, thoroughness, or pace. Phrase every suggestion positively: point toward the helpful next step rather than dwelling on what was missed. Say "the earlier benchmarks page already had this figure", not "you keep re-searching something you found".

package/ai/personas/security.md

@@ -0,0 +1,12 @@
+[//]: # opencode:google/gemini-3.1-flash-lite:default
+
+You are a security monitor. You watch the transcript of one or more terminal agent tabs and look exclusively for security problems:
+
+- Secrets, tokens, API keys, or credentials appearing in command output
+- Risky commands: piping downloads straight into a shell, chmod 777, disabling TLS verification, force-pushes to shared branches
+- Unsafe patterns in code being written: injection-prone string building, eval on user input, weak crypto
+- Files with sensitive content (e.g. .env, private keys) being printed, copied, or committed
+
+You never run commands and never take action yourself. When you spot a problem, respond with a short, concrete suggestion. Do not comment on anything that is not a security concern — if the activity you see is fine, respond with nothing at all.
+
+Never say anything negative about the user or their work — no blame, no alarm about their judgment. Phrase findings positively and constructively: focus on the protective action to take, not the mistake. Say "rotating this key keeps the account safe", not "you exposed a secret".

package/ai/personas/summarizer.md

@@ -0,0 +1,11 @@
+[//]: # opencode:google/gemini-3.1-flash-lite:default
+
+You are a summarizing monitor. You watch the transcript of one or more terminal agent tabs as a long-running session accumulates, and you periodically keep the state legible with a short "here's where things stand":
+
+- The decisions that have been made and what they settled
+- The open questions and anything still unresolved
+- What has been done so far and what appears to come next
+
+You never run commands and never take action yourself, and you never suggest one — your only job is to reflect the current state back clearly. Keep each summary brief and skimmable. If nothing meaningful has changed since your last summary, respond with nothing at all — silence is better than a redundant recap.
+
+Never say anything negative about the user or their work — no criticism of their choices, progress, or pace. Phrase the state neutrally and constructively: describe where things stand rather than judging how they got there. Say "the auth approach is still open", not "the auth approach still hasn't been figured out".

package/ai/tasks/build-a-feature.md

@@ -0,0 +1,133 @@
+# Build a Feature
+
+Your job: pick the simplest available plan from `product/plans/ready/`, implement it end to end, update the functional specs, promote the plan to `product/plans/complete/`, and open a pull request. You change source code, tests, spec files, and the plan file's location — nothing else.
+
+**No AI attribution — anywhere.** Never credit an AI agent as an author or contributor in anything this task produces. That means: no `Co-Authored-By:` trailers naming Claude or any other AI, no “Generated with Claude Code” (or similar) lines or badges, and no AI authorship notes in code, comments, docs, spec files, plan files, commit messages, or PR titles and bodies. This overrides any default convention that appends such attribution. The commit's configured git author is the only authorship ever recorded.
+
+**Shell hygiene:** run every command on its own line — no `&&` chaining, no `; echo "Exit code: $?"` suffixes, no subshell captures, no `for`/`while` loops, no variable expansion (`$var`, `$(...)`), no redirects (`2>/dev/null`, `>file`, `>>file`), no pipes (`|`). Commands with control-flow, expansion, redirects, or pipes require manual approval and will stall an unattended run. To run a project script, always use `./scripts/run.mjs <name>` — never call `node scripts/<name>.mjs` directly.
+
+**Run everything synchronously, in the foreground.** Never use `run_in_background`, `&`, or otherwise start a background process (dev servers, watchers, long-lived processes) — every command must finish and return its exit code before you move to the next step.
+
+**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to research, explore, or implement any part of this task on your behalf.
+
+**Run autonomously.** This task runs unattended — do not ask the user questions or wait for feedback at any step. Make the best judgment call yourself, using the rules in this document, and keep going. Only stop early for the conditions explicitly listed under "Forbidden" below (e.g. no plans available, only 7+ complexity plans, discovering out-of-scope file edits).
+
+**Stay within the project directory.** The current working directory is the project directory for this session. Do not read or write any file outside it — no absolute paths escaping the project root, no `..` traversal above it, no touching files elsewhere on the machine (home directory config, other repos, system paths).
+
+## What you may and may not do
+
+### Allowed — do it automatically, never ask
+
+Read any file in the repo. Edit source, tests, CSS, and spec files as the plan directs. Move the chosen plan file from `product/plans/ready/` to `product/plans/complete/`. Run `./scripts/run.mjs check-diff` after each change. Run the full PR workflow via `ai/tasks/open-feature-pull-request.md` when implementation is done.
+
+### Forbidden — no exceptions
+
+1. **Editing files the plan does not touch.** Stay inside the plan's scope. If you discover the plan missed a file, stop and report — do not silently expand scope.
+2. **Running `npm run check`.** That is the human's end-of-work gate. Use `./scripts/run.mjs check-diff` during development.
+3. **Skipping tests.** If the plan specifies tests, write them. If it does not, still verify with `./scripts/run.mjs check-diff`.
+4. **Choosing a plan at complexity 7 or above.** If every plan in `product/plans/ready/` is rated 7+, stop and report — do not pick one anyway.
+5. **Merging the PR.** `ai/tasks/open-feature-pull-request.md` opens it; merging is the human's decision.
+
+---
+
+## Step 0 — Prepare the workspace
+
+Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
+
+---
+
+## Step 1 — List ready plans and pick the simplest
+
+1. List every `.md` file in `product/plans/ready/`.
+2. For each file, use the `Read` tool to read the first few lines and find the complexity rating line: `**Complexity: N/10**`. Do not use a shell loop to do this.
+3. If no plans exist, report "No plans in `product/plans/ready/`" and stop.
+4. If the lowest complexity found is **7 or above**, report the list with ratings and stop — do not pick one.
+5. Otherwise, pick the plan with the **lowest** complexity number. On a tie, pick whichever plan name comes first alphabetically.
+
+State your pick and its complexity in one sentence.
+
+---
+
+## Step 2 — Read the plan and the project constraints
+
+1. Read the entire chosen plan.
+2. Read the project constraints that shape implementation: the ESLint rules and file-size limit in [`CLAUDE.md`](../../CLAUDE.md) (200-line `max-lines`, `.js` import extensions in `src/`, type-aware rules), and the test conventions (`src/**/*.test.ts`, `web/src/**/*.test.tsx`).
+3. Read every file the plan references to confirm the line anchors and code fragments still match. If a reference is stale, locate the correct position by the quoted code fragment — line numbers drift.
+
+---
+
+## Step 3 — Implement the plan
+
+Follow the plan's implementation steps **in order**. After each step:
+
+1. Run `./scripts/run.mjs check-diff` to catch lint, typecheck, and test failures immediately.
+2. Fix any failures before moving to the next step.
+3. If a step produces a file over the 200-line limit, extract into a new module per `ai/guidelines/code-guidelines.md` — do not compact code, strip comments, or delete spacing.
+
+Key rules during implementation:
+
+- **Match existing conventions.** Use the same libraries, patterns, and naming the surrounding code uses. Check `package.json` or the file's existing imports before assuming a library is available.
+- **Import extensions.** Relative imports in `src/` must carry `.js` (NodeNext). Relative imports in `web/src/` stay extensionless.
+- **No comments unless the plan specifies them.** Write clean code; let it speak for itself.
+- **Every file the plan names, touch.** Every file the plan does not name, leave alone.
+
+---
+
+## Step 4 — Write the tests
+
+If the plan has a Tests section, implement every test case listed. Mirror the test style of the referenced test files (imports, helper patterns, assertion style).
+
+Run `./scripts/run.mjs check-diff` after writing tests. All tests must pass.
+
+---
+
+## Step 5 — Update or create spec files
+
+Every feature must be reflected in the functional specs under `product/specs/`. After implementation and tests:
+
+1. **Check the plan.** If the plan names specific spec files to update or create, do exactly that.
+2. **Otherwise, find the right spec.** Read the existing specs in `product/specs/` and identify which one(s) the feature belongs to. Most features extend an existing spec (e.g. a new keyboard shortcut belongs in `product/specs/keyboard-navigation.md`, a new tab behavior belongs in `product/specs/tabs.md`). If no existing spec covers the area, create a new one.
+3. **Write or update the spec.** Follow the existing conventions: `# Title` at the top, `### Subsection` for each aspect, prose describing user-visible behavior only — no code, no implementation details, no file paths. The spec is what the feature *does*, not how it is built. Keep additions concise and factual.
+
+Spec files are markdown and do not affect `check-diff`, so no verification run is needed after this step.
+
+---
+
+## Step 6 — Final verification
+
+1. Run `./scripts/run.mjs check-diff` one last time. It must pass clean.
+2. Manually verify the behavior if the plan's Verification section describes manual steps. If manual verification is not possible in this environment, note that in the report.
+
+---
+
+## Step 7 — Promote the plan
+
+Move the plan file from `product/plans/ready/` to `product/plans/complete/`:
+
+```bash
+git mv product/plans/ready/<plan-file> product/plans/complete/<plan-file>
+```
+
+---
+
+## Step 8 — Open the pull request
+
+Execute `ai/tasks/open-feature-pull-request.md` in full. That document owns the PR workflow — follow its steps without deviation.
+
+---
+
+## Step 9 — Report
+
+Give the user a short report in this exact shape:
+
+```
+Plan:           product/plans/ready/<file> → product/plans/complete/<file>
+Complexity:     N/10
+Implementation: <one-line summary of what was built>
+Tests:          <count> new tests across <files>
+Spec:           <spec file(s) created or updated, with one-line description of change>
+PR:             <url> (#<number>)
+Status:         open
+```
+
+Keep it brief. Done.