@mohammadhprp/system-prompt 0.12.0 → 0.12.2

package/framework/skills/improve/references/closing-the-loop.md

@@ -0,0 +1,96 @@
+# Closing the Loop — execute, reconcile, issues
+
+The advisor's job doesn't end at the plan. This file covers the three follow-through flows: dispatching an executor and reviewing its work (`execute`), keeping the plan backlog alive (`reconcile`), and publishing plans where work gets picked up (`--issues`).
+
+The founding rule survives unchanged: **the advisor never edits source code.** In `execute`, a *separate executor subagent* edits code in an isolated git worktree; the advisor dispatches, reviews, and renders a verdict — like a tech lead who doesn't push commits to your branch.
+
+---
+
+## `execute <plan>` — dispatch and review
+
+### Preconditions (check all before dispatching)
+
+- The repo is a git repository (worktree isolation requires it). If not: stop and say so.
+- The plan file exists and its dependencies show DONE in `plans/README.md`. If not: stop, name the missing dependency.
+- Run the plan's drift check yourself. If in-scope files changed since `Planned at`, reconcile the plan first (see below) — don't hand a stale plan to an executor.
+
+### Dispatch
+
+Spawn **one** `general-purpose` subagent with `isolation: "worktree"`. Executor model: default `sonnet`; use what the user named if they named one (`execute 003 haiku`).
+
+The subagent prompt must contain:
+
+1. **The full plan file text, inlined.** The worktree contains only committed files — if `plans/` is uncommitted, the executor can't read it. Never assume; always inline.
+2. The executor preamble:
+
+> You are the executor for the implementation plan below. Follow it step by
+> step. Run every verification command and confirm the expected result before
+> moving on. Touch only the files listed as in scope. If any STOP condition
+> occurs, stop immediately and report. Do not improvise around obstacles.
+> Commit your work in the worktree following the plan's git workflow section.
+> One override: SKIP the plan's instruction to update `plans/README.md` —
+> your reviewer maintains the index. Before reporting, audit every claim in
+> your report against an actual tool result from this session — only report
+> what you can point to evidence for; if a verification failed or was
+> skipped, say so plainly. When finished, reply with exactly the report
+> format below.
+
+3. The report format:
+
+```
+STATUS: COMPLETE | STOPPED
+STEPS: per step — done/skipped + verification command result
+STOPPED BECAUSE: (only if STOPPED) which STOP condition, what was observed
+FILES CHANGED: list
+NOTES: anything the reviewer should know (deviations, surprises, judgment calls)
+```
+
+### Review (the advisor's real job here)
+
+Note on fresh worktrees: they share git history but not `node_modules` or build artifacts — the executor must install dependencies first, and check tooling that resolves from `dist/` may need one build even though the plan's command table (recon'd in the main tree) didn't mention it. Expect this; it isn't a deviation.
+
+Review like a tech lead reviewing a PR against the spec — never fix anything yourself:
+
+1. **Re-run every done criterion** in the worktree. Don't trust the executor's report — verify.
+2. **Scope compliance**: `git -C <worktree> diff --stat` against the plan's in-scope list. Any file outside scope fails review, full stop.
+3. **Read the full diff.** Judge it against "Why this matters" (does it solve the actual problem?) and the repo conventions named in the plan (does it look like the rest of the codebase?).
+4. **Audit the new tests.** Executors game criteria — a test that asserts nothing meaningful passes `pnpm test` and proves nothing. Read what the tests assert.
+
+### Verdict
+
+**Documented deviations are judged on merit, not reflex-blocked.** "Do not improvise" exists to stop silent drift; an executor that hits a real obstacle (e.g. the plan's approach breaks existing test mocks), adapts minimally, and explains it in NOTES has done the right thing. Approve it if the adaptation serves the plan's intent and stays in scope; treat *undocumented* deviations as review failures.
+
+| Verdict | When | Action |
+|---|---|---|
+| **APPROVE** | Criteria pass, scope clean, quality holds | Update index status to DONE. Present to the user: diff summary, worktree path and branch, anything from NOTES. **Merging is the user's decision — never merge, push, or commit to their branch.** |
+| **REVISE** | Fixable gaps | SendMessage to the same executor with specific, actionable feedback ("criterion 3 fails: X; the error handling in `api.ts:90` swallows the error — use the Result pattern per the plan"). **Max 2 revision rounds**, then BLOCK. |
+| **BLOCK** | STOP condition hit, scope violated unrecoverably, or revisions exhausted | Mark BLOCKED in the index with the reason. Refine or rewrite the plan with what was learned. Tell the user what happened and what changed in the plan. |
+
+Running verification commands inside the executor's worktree is fine — it's isolated and disposable. The no-mutating-commands rule protects the user's working tree, not the worktree.
+
+---
+
+## `reconcile` — keep `plans/` alive
+
+Process what happened since the last session. Read `plans/README.md` and every plan file, then per status:
+
+- **DONE** — spot-check that the done criteria still hold on the current HEAD (cheap ones only). Mark verified in the index. Don't delete plan files — they're the record.
+- **BLOCKED** — read the reason. Investigate the underlying obstacle in the codebase. Either rewrite the plan around it (new number if the approach changed fundamentally, in-place refresh otherwise) or mark REJECTED with one line of rationale.
+- **IN PROGRESS** (stale) — flag it to the user; an executor probably died mid-run. Check the worktree if one exists.
+- **TODO** — run the drift check. If drifted: re-verify the finding still exists (it may have been fixed in passing), then refresh the "Current state" excerpts and `Planned at` SHA. If the finding is gone, mark REJECTED ("fixed independently").
+
+Finish with a short report: what's verified done, what was refreshed, what's rejected, and what's executable right now.
+
+---
+
+## `--issues` — publish plans as GitHub issues
+
+Modifier on any planning invocation (`/improve --issues`, `/improve security --issues`). The flag is the user's authorization to create issues — never create them without it.
+
+1. Preflight: `gh auth status` succeeds and the repo has a GitHub remote. If either fails, write the plan files as normal and say why issues were skipped.
+2. Visibility check: `gh repo view --json visibility`. If the repo is **public**, warn the user that issues are publicly visible and get explicit confirmation before publishing any plan that describes a security vulnerability, credential location, or other sensitive finding.
+3. Show the list of titles about to become issues; confirm once if interactive.
+4. Per plan: `gh issue create --title "<plan title>" --body-file <plan file>`. Labels: `improve` plus the category — apply only if the labels exist or can be created without erroring; skip labels rather than fail.
+5. Record each issue URL in the plan's Status block (`- **Issue**: <url>`) and the index.
+
+The plan file remains the source of truth; the issue is distribution. The self-containment rule pays off here — the issue body needs no edits to make sense to whoever (or whatever) picks it up.

package/framework/skills/improve/references/plan-template.md

@@ -0,0 +1,197 @@
+# Handoff Plan Template
+
+Every plan is written for an executor model that has **zero context**: it has not seen the advisor session, the audit, the other plans, or any prior conversation. It may be a smaller/cheaper model. Assume it is competent at following explicit instructions and weak at filling gaps, recovering from ambiguity, or knowing when to stop.
+
+Three properties make a plan executable by a weaker model:
+
+1. **Self-contained context** — everything needed is in the file: paths, code excerpts, conventions, commands.
+2. **Verification gates** — every step ends with a command and its expected result. The executor never has to *judge* whether it succeeded.
+3. **Hard boundaries and escape hatches** — explicit out-of-scope list, and "STOP and report" conditions instead of letting the model improvise when reality doesn't match the plan.
+
+File naming: `plans/NNN-short-slug.md`, numbered in recommended execution order.
+
+---
+
+## Template
+
+```markdown
+# Plan NNN: <Imperative title — what will be true after this plan>
+
+> **Executor instructions**: Follow this plan step by step. Run every
+> verification command and confirm the expected result before moving to the
+> next step. If anything in the "STOP conditions" section occurs, stop and
+> report — do not improvise. When done, update the status row for this plan
+> in `plans/README.md` — unless a reviewer dispatched you and told you they
+> maintain the index.
+>
+> **Drift check (run first)**: `git diff --stat <planned-at SHA>..HEAD -- <in-scope paths>`
+> If any in-scope file changed since this plan was written, compare the
+> "Current state" excerpts against the live code before proceeding; on a
+> mismatch, treat it as a STOP condition.
+
+## Status
+
+- **Priority**: P1 | P2 | P3
+- **Effort**: S | M | L
+- **Risk**: LOW | MED | HIGH
+- **Depends on**: plans/NNN-*.md (or "none")
+- **Category**: bug | security | perf | tests | tech-debt | migration | dx | docs | direction
+- **Planned at**: commit `<short SHA>`, <YYYY-MM-DD>
+- **Issue**: <GitHub issue URL — only when published via `--issues`; omit otherwise>
+
+## Why this matters
+
+2–5 sentences. The problem, its concrete cost, and what improves when this
+lands. Written so the executor (and a human reviewer) understands the intent —
+intent is what lets a correct judgment call happen when a detail is off.
+
+## Current state
+
+The facts the executor needs, inlined — never "as discussed" or "see audit":
+
+- The relevant files, each with one line on its role:
+  - `src/orders/api.ts` — order-list endpoint; contains the N+1 (lines 130–160)
+- Excerpts of the code as it exists today (short, with `file:line` markers),
+  enough that the executor can confirm it's looking at the right thing.
+- The repo conventions that apply here, with a pointer to one exemplar file:
+  "Error handling follows the Result pattern — see `src/lib/result.ts` and its
+  use in `src/users/api.ts:40-60`. Match it."
+- Any documented vocabulary or design constraints the plan must honor, inlined
+  from the intent/design docs found in recon: the relevant `CONTEXT.md` terms
+  the executor should use in names and comments, the `DESIGN.md` tokens/components
+  to reuse, or the ADR whose decision this work must stay consistent with. Quote
+  the specific lines — the executor has not read those docs.
+
+## Commands you will need
+
+| Purpose   | Command                  | Expected on success |
+|-----------|--------------------------|---------------------|
+| Install   | `pnpm install`           | exit 0              |
+| Typecheck | `pnpm typecheck`         | exit 0, no errors   |
+| Tests     | `pnpm test -- <filter>`  | all pass            |
+| Lint      | `pnpm lint`              | exit 0              |
+
+(Exact commands from this repo — verified during recon, not guessed.)
+
+## Suggested executor toolkit
+
+(Optional — include only when relevant skills/tools plausibly exist in the
+executor's environment. Skip the section otherwise.)
+
+- Skills the executor should invoke if available, and for what:
+  "use `vercel-react-best-practices` when writing the memoization in step 3".
+- Reference docs worth reading before starting, by path or URL.
+
+## Scope
+
+**In scope** (the only files you should modify):
+- `src/orders/api.ts`
+- `src/orders/api.test.ts` (create)
+
+**Out of scope** (do NOT touch, even though they look related):
+- `src/orders/legacy-api.ts` — deprecated path, scheduled for deletion;
+  changing it wastes effort and risks the v1 clients still pinned to it.
+- Any change to the public response shape — clients depend on it.
+
+## Git workflow
+
+(Filled from recon — match the repo's observed conventions.)
+
+- Branch: `advisor/NNN-<slug>` (or the repo's branch-naming convention if one is evident)
+- Commit per step or per logical unit; message style: <match repo, e.g. conventional commits — include an example from `git log`>
+- Do NOT push or open a PR unless the operator instructed it.
+
+## Steps
+
+### Step 1: <imperative title>
+
+What to do, precisely. Reference exact files/symbols. Include the target code
+shape when it's load-bearing (the pattern to produce, not necessarily every
+line).
+
+**Verify**: `<command>` → <expected output>
+
+### Step 2: ...
+
+(Each step small enough to verify independently. Order steps so the codebase
+is never broken between steps when possible — e.g. add new path, switch
+callers, then remove old path.)
+
+## Test plan
+
+- New tests to write, in which file, covering which cases (list them:
+  happy path, the specific bug/regression this plan fixes, named edge cases).
+- Which existing test to use as the structural pattern:
+  "model after `src/users/api.test.ts`".
+- Verification: `<test command>` → all pass, including N new tests.
+
+## Done criteria
+
+Machine-checkable. ALL must hold:
+
+- [ ] `pnpm typecheck` exits 0
+- [ ] `pnpm test` exits 0; new tests for <X> exist and pass
+- [ ] `grep -rn "<old pattern>" src/` returns no matches
+- [ ] No files outside the in-scope list are modified (`git status`)
+- [ ] `plans/README.md` status row updated
+
+## STOP conditions
+
+Stop and report back (do not improvise) if:
+
+- The code at the locations in "Current state" doesn't match the excerpts
+  (the codebase has drifted since this plan was written).
+- A step's verification fails twice after a reasonable fix attempt.
+- The fix appears to require touching an out-of-scope file.
+- You discover the assumption "<key assumption>" is false.
+
+## Maintenance notes
+
+For the human/agent who owns this code after the change lands:
+
+- What future changes will interact with this (e.g. "if pagination is added
+  to this endpoint, the batching in step 2 must be revisited").
+- What a reviewer should scrutinize in the PR.
+- Any follow-up explicitly deferred out of this plan (and why).
+```
+
+---
+
+## Index file: `plans/README.md`
+
+Written once by the advisor after all plans, updated by executors:
+
+```markdown
+# Implementation Plans
+
+Generated by the improve skill on <date>. Execute in the order below unless
+dependencies say otherwise. Each executor: read the plan fully before starting,
+honor its STOP conditions, and update your row when done.
+
+## Execution order & status
+
+| Plan | Title | Priority | Effort | Depends on | Status |
+|------|-------|----------|--------|------------|--------|
+| 001  | ...   | P1       | S      | —          | TODO   |
+| 002  | ...   | P1       | M      | 001        | TODO   |
+
+Status values: TODO | IN PROGRESS | DONE | BLOCKED (with one-line reason) | REJECTED (with one-line rationale — finding fixed independently or approach abandoned)
+
+## Dependency notes
+
+- 002 requires 001 because <reason>.
+
+## Findings considered and rejected
+
+- <finding>: not worth doing because <one line>. (So nobody re-audits it.)
+```
+
+## Quality bar — check before finishing each plan
+
+- Could a model that has never seen this repo execute this with only the plan file and the repo? If any step requires knowledge from the advisor session, inline that knowledge.
+- Is every verification a command with an expected result, not a judgment ("make sure it works")?
+- Does every step name exact files and symbols, not "the relevant module"?
+- Are the STOP conditions specific to this plan's actual risks, not boilerplate?
+- Would a reviewer reading only "Why this matters" + "Done criteria" understand what they're approving?
+- No secret values anywhere in the file — locations and credential types only.
+- "Planned at" SHA is filled in and the in-scope paths in the drift check match the Scope section.

package/framework/skills/jira-cli/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: jira-cli
+description: Expert guidance for using the Jira CLI (jira) to manage Jira issues, sprints, epics, comments, transitions, and worklogs from the command line. Use this skill when the user needs to interact with Jira resources or perform Jira workflows — listing, creating, editing, or transitioning issues, running JQL queries, or scripting against Jira data — even if they don't explicitly mention the jira CLI.
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Jira CLI (jira) Skill
+
+Provides guidance for using `jira`, the feature-rich interactive Jira command line, to perform Jira operations from the terminal.
+
+## When to Use This Skill
+
+Invoke when the user needs to:
+- Search, list, or view Jira issues
+- Create, edit, assign, clone, or transition issues
+- Add comments, links, or worklogs to issues
+- Work with epics, sprints, releases, or project boards
+- Run JQL queries or script against Jira data
+
+## Prerequisites
+
+Verify jira installation before executing commands:
+```bash
+jira --version
+```
+
+If not installed, inform the user and provide platform-specific installation guidance.
+
+## Setup Quick Start
+
+`jira` requires one-time initialization before first use:
+
+```bash
+# Interactive setup wizard: installation type (Cloud/Local), auth type, project, board
+jira init
+```
+
+Authentication via environment variables:
+
+```bash
+# Jira Cloud: API token from https://id.atlassian.com/manage-profile/security/api-tokens
+export JIRA_API_TOKEN=your-token
+
+# On-premises with a Personal Access Token
+export JIRA_API_TOKEN=your-token
+export JIRA_AUTH_TYPE=bearer
+```
+
+- Use `jira issue list -c /path/to/config.yaml` or `export JIRA_CONFIG_FILE=/path/to/config.yaml` to work with multiple projects or instances
+- Check authentication and current user: `jira me`
+
+## Core Workflows
+
+### Searching and Viewing Issues
+
+```bash
+# 1. List issues assigned to you (sorted by created, descending)
+jira issue list -a$(jira me) --plain
+
+# 2. Combine filters: high priority, open, created this month, label backend
+jira issue list -yHigh -s"To Do" --created month -lbackend -a$(jira me) --plain
+
+# 3. View issue details with recent comments
+jira issue view ISSUE-1 --comments 5
+```
+
+Filter flags: `-a` assignee, `-r` reporter, `-s` status (prefix `~` for "not"), `-y` priority, `-l` label (repeatable), `-t` type, `-w` watching, `-R` resolution, `--created`/`--updated` with values like `-7d`, `week`, `month`.
+
+> **IMPORTANT:** list commands open an interactive TUI by default. Always pass `--plain` (or `--table`, `--raw`, `--csv`) when running non-interactively, or the command will hang waiting for keyboard input.
+
+### Creating an Issue
+
+```bash
+# 1. Non-interactive creation with all required fields
+jira issue create -tBug -s"New Bug" -yHigh -lbug -b"Bug description" --no-input
+
+# 2. Attach to an epic on creation
+jira issue create -tStory -s"Summary" -PEPIC-42 --no-input
+
+# 3. Body from stdin or template
+echo "Description from stdin" | jira issue create -s"Summary" -tTask --no-input
+jira issue create --template /path/to/template.tmpl -s"Summary" -tTask --no-input
+```
+
+Supports GitHub-flavored and Jira-flavored Markdown in descriptions and comments. Use `--custom "key=value"` for custom fields.
+
+### Editing and Assigning
+
+```bash
+# Edit summary, priority, labels
+jira issue edit ISSUE-1 -s"Updated summary" -yHigh -lbug --no-input
+
+# Prefix minus (-) removes labels, components, or fix versions
+jira issue edit ISSUE-1 --label -p2 --label p1 --fix-version -v1.0 --fix-version v2.0 --no-input
+
+# Assign to a user, to self, to default, or unassign
+jira issue assign ISSUE-1 "Jon Doe"
+jira issue assign ISSUE-1 $(jira me)
+jira issue assign ISSUE-1 default
+jira issue assign ISSUE-1 x
+```
+
+### Transitioning Issues
+
+```bash
+# Move an issue to a new status (name must match the workflow exactly)
+jira issue move ISSUE-1 "In Progress"
+
+# Move with comment, resolution, and assignee
+jira issue move ISSUE-1 Done -RFixed -a$(jira me) --comment "Completed"
+```
+
+### Comments, Links, and Worklogs
+
+```bash
+# Add a comment (positional body, template, or stdin)
+jira issue comment add ISSUE-1 "My comment body"
+
+# Internal (restricted) comment
+jira issue comment add ISSUE-1 "Internal note" --internal
+
+# Link two issues with a link type such as Blocks, Relates, Duplicates
+jira issue link ISSUE-1 ISSUE-2 Blocks
+
+# Add a remote web link
+jira issue link remote ISSUE-1 https://example.com "Example text"
+
+# Log work: time is positional, e.g. "2d 3h 30m"
+jira issue worklog add ISSUE-1 "2d 3h 30m" --comment "Implementation" --no-input
+```
+
+### Sprints and Epics
+
+```bash
+# List issues in the current active sprint
+jira sprint list --current -a$(jira me) --table --plain
+
+# List issues in a specific sprint (get the ID from `jira sprint list`)
+jira sprint list SPRINT_ID -yHigh --table --plain
+
+# Add up to 50 issues to a sprint
+jira sprint add SPRINT_ID ISSUE-1 ISSUE-2
+
+# List issues in an epic
+jira epic list EPIC-1 --table --plain
+
+# Create an epic (epic name via -n is required)
+jira epic create -n"Epic epic" -s"Everything" -b"Epic description" --no-input
+
+# Add or remove issues in an epic (up to 50 at once)
+jira epic add EPIC-1 ISSUE-1 ISSUE-2
+jira epic remove ISSUE-1 ISSUE-2
+```
+
+## Common Patterns
+
+### Scripting and Automation
+
+The default view is an interactive UI. For shell pipelines, use machine-friendly output:
+
+```bash
+# Tab-separated plain output with selected columns, no headers
+jira issue list -a$(jira me) --plain --columns key,summary,status --no-headers
+
+# Raw JSON or CSV for parsing
+jira issue list --raw
+jira issue list --csv
+```
+
+### JQL Queries
+
+Execute raw JQL within the configured project context using `-q/--jql`:
+
+```bash
+jira issue list -q "summary ~ cli AND status != Done"
+```
+
+### Working With a Different Project
+
+Use `-p KEY` to target a project other than the one in the config:
+
+```bash
+jira issue list -pXYZ -a$(jira me) --plain
+```
+
+### Navigation Shortcuts (Interactive Mode Only)
+
+In the default TUI: `v` view issue, `m` transition, `ENTER` open in browser, `c` copy URL, `q` quit. Not usable in scripts — use `--plain` instead.
+
+## Best Practices
+
+1. **Verify setup first**: `jira me` confirms auth and config are working
+2. **Always pass `--no-input` with explicit flags** in scripts; interactive prompts will hang
+3. **Use `$(jira me)`** for self-assignment and self-filtering
+4. **Use `--plain --columns ... --no-headers`** for any output you intend to parse
+5. **Match transition names exactly** to the Jira workflow; list interactively first if unsure
+
+## Common Commands Quick Reference
+
+**Issues:**
+- `jira issue list -a$(jira me) --plain` - Your assigned issues
+- `jira issue list -w` - Issues you are watching
+- `jira issue list --history` - Issues you recently interacted with
+- `jira issue create -tBug -s"Summary" -b"Body" --no-input` - Create issue
+- `jira issue view ISSUE-1 --comments 5` - View details
+- `jira issue move ISSUE-1 "In Progress"` - Transition issue
+- `jira issue clone ISSUE-1 -s"New summary"` - Clone with modifications
+- `jira issue delete ISSUE-1 --cascade` - Delete with subtasks
+
+**Epics:**
+- `jira epic list` - List epics
+- `jira epic list EPIC-1` - List issues in an epic
+- `jira epic create -n"Name" -s"Summary" --no-input` - Create epic
+
+**Sprints:**
+- `jira sprint list --current --table --plain` - Current sprint issues
+- `jira sprint list --prev --table --plain` - Previous sprint issues
+- `jira sprint add SPRINT_ID ISSUE-1 ISSUE-2` - Add issues to sprint
+
+**Projects and Boards:**
+- `jira project list` - List accessible projects
+- `jira board list` - List boards in the configured project
+- `jira open ISSUE-1` - Open issue in browser
+- `jira me` - Show current user
+
+## Progressive Disclosure
+
+For detailed command documentation, refer to:
+- **references/commands-detailed.md** - Comprehensive command reference with all flags and options
+- **references/quick-reference.md** - Condensed command cheat sheet
+- **references/troubleshooting.md** - Detailed error scenarios and solutions
+
+Load these references when:
+- User needs specific flag or option details
+- Troubleshooting authentication, config, or permission issues
+- Working with advanced features (JQL, custom fields, multiple configs)
+
+## Common Issues Quick Fixes
+
+**"command not found: jira"** - Install jira-cli or verify PATH
+
+**Auth errors (401/403)** - Check `JIRA_API_TOKEN` is exported; for on-premises PAT auth set `JIRA_AUTH_TYPE=bearer`
+
+**"Please select installation type" / config missing** - Run `jira init` to generate the config
+
+**List command hangs in a script** - The default output is an interactive TUI; add `--plain`
+
+**"Transition not found" or move fails** - Status name must match the workflow exactly; run `jira issue move` without arguments to see valid transitions
+
+**Empty issue lists** - Verify the project/board chosen during `jira init`; try `-p PROJECT_KEY`
+
+For detailed troubleshooting, load **references/troubleshooting.md**.
+
+## Notes
+
+- Works with both Jira Cloud and on-premises (Server/Data Center) installations
+- Supports `basic`, `bearer` (PAT), and `mtls` (client certificates) auth types
+- Sprint lists show only the 25 most recent sprints
+- Descriptions and comments accept GitHub-flavored and Jira-flavored Markdown
+- Shell completion is available via `jira completion --help`