@jehudarajasa/agency-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jehuda Rajasa
+
+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/config.example.yml

@@ -0,0 +1,22 @@
+# .agents/config.yml — copy this to your project root and trim to taste.
+# Every field is optional. The skills read `git remote` first and only fall
+# back here for what the environment can't reveal: your team's state names,
+# labels, and branch conventions.
+
+# Which tracker and which project. Omit both when your git remote already
+# names them (GitHub / GitLab). Required for Jira, Linear, or a self-hosted
+# host the remote can't identify.
+tracker: gitlab            # gitlab | github | jira | linear
+project: group/repo        # the tracker's project id or slug
+
+# Used by `fetch-issues`: which issue states count as "workable, not done".
+active_states: [Open, "To Do", Staging, WIP]
+
+# Used by planning, implementation, and opening a change request:
+# the states the workflow moves an issue into.
+states:
+  in_progress: WIP
+  review: "In Review"
+
+# open-change-request: what your tracker calls the review artifact.
+change_request: MR         # MR (GitLab) | PR (GitHub, Bitbucket)

package/index.js

@@ -0,0 +1,15 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const skillsPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "skills");
+
+export default async () => ({
+  config(config) {
+    config.skills ??= {};
+    config.skills.paths ??= [];
+
+    if (!config.skills.paths.includes(skillsPath)) {
+      config.skills.paths.push(skillsPath);
+    }
+  },
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@jehudarajasa/agency-skills",
+  "version": "1.0.0",
+  "description": "Tracker-agnostic skills for issue-driven software development workflows.",
+  "keywords": [
+    "opencode-plugin",
+    "opencode",
+    "agent-skills",
+    "software-development"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Jehuda Rajasa",
+    "email": "jehudarajasa@gmail.com"
+  },
+  "homepage": "https://github.com/jehudarajasa/skills",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jehudarajasa/skills.git",
+    "directory": "plugins/agency-skills"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "exports": "./index.js",
+  "files": [
+    "index.js",
+    "skills/",
+    "references/",
+    "config.example.yml",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/issue-tracker.md

@@ -0,0 +1,27 @@
+# Resolving the tracker
+
+Every skill that touches issues or change requests resolves the tracker the same way. Read this before the skill's own steps.
+
+## Which tracker, which project
+
+Read the environment before opening config:
+
+1. `git remote get-url origin` — a `github.com` host means GitHub (use the `gh` CLI or a GitHub MCP); a GitLab host means GitLab (use `glab` or a GitLab MCP).
+2. If the remote does not name the tracker (Jira, Linear, or a self-hosted host you cannot identify) read `tracker` and `project` from `.agents/config.yml` in the project root.
+
+## Who "the user" is
+
+Resolve the user's identity from the tracker's own authenticated account — GitLab `whoami`, `gh api user`, the Linear or Jira viewer. Carry no name or email in any skill.
+
+## Moving an issue's state
+
+`plan-implementation` and `implement-change` mark work started with `states.in_progress`; `open-change-request` marks code ready for review with `states.review`. These are the skills that move issues. If the issue already has the target state, leave it there.
+
+Move the issue only when `.agents/config.yml` maps the state for that action (`states.in_progress`, `states.review`). When the mapping is absent, leave the board untouched.
+
+When the mapping is present:
+
+- Set only a state or label that already exists on the board. Read the board's current states first and match the configured value against them.
+- When nothing matches (the value is wrong, or the label was renamed) stop and show the user the states that exist, then ask which to use. Never mint a new label or state.
+- Echo the move before making it: "moving #42 → Dev Review".
+- If the tracker models state as labels, drop the previous workflow label as you add the new one, so the issue never carries two.

package/references/issue-workspace.md

@@ -0,0 +1,40 @@
+# The issue workspace
+
+Saved plans and their context live at `.issues/<issue-id>-<slug>/` in the repo root. Planning, re-planning, implementation, and re-orientation use this layout when a workspace exists. Direct implementation needs no workspace.
+
+## Where it lives
+
+- Name the directory `<issue-id>-<slug>` — the branch `cut-branch` made, with its `<type>/` prefix removed. With no issue in the branch, slug the user's request instead and tell the user.
+- Create the workspace only when saving a plan or its context.
+- To find an existing workspace, use the resolved issue id (the argument, else the current branch, else the issue under discussion) and glob `.issues/<issue-id>-*/`.
+
+## PLAN.md
+
+The plan you synthesize. Use these sections:
+
+```markdown
+# Issue <issue-id> — <short title>
+
+**Branch:** <branch-name> **Created:** <YYYY-MM-DD> **Status:** Planned
+
+## Acceptance Criteria
+
+<Observable conditions that must all hold for this issue to be complete.>
+
+## Design (optional)
+
+<Include when decisions govern multiple tasks. Record the chosen approach, its rationale, and relevant constraints. Put task-specific details with their task. Omit this section when the tasks convey the approach fully.>
+
+## Tasks
+
+- [ ] <step 1>
+- [ ] <step 2>
+```
+
+`Status` moves `Planned` → `In Progress` → `Done` as the work proceeds.
+
+Record decisions and remaining caveats beside the affected design or task. As answers arrive, replace resolved assumptions with the resulting decisions or acceptance criteria.
+
+## CONTEXT.md
+
+The raw, accreting context the plan draws on — standup notes, Slack quotes, huddle decisions. Free-form, appended to as new context surfaces. Write it only when context beyond the issue itself exists; skip it when the issue stands on its own.

package/skills/commit/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: commit
+description: Commit the working tree as small Conventional Commits.
+disable-model-invocation: true
+---
+
+Turn the working tree into small, well-formed commits: read what changed, stage one concern at a time by name, and write each message in Conventional Commits form. Review the staged diff before every commit.
+
+## Read the tree
+
+Run `git status` and `git diff` to see everything uncommitted. A clean tree means nothing to do — say so and stop. Otherwise group the changes by concern, where each distinct purpose is its own commit.
+
+## Stage one concern
+
+Stage that concern's files by name with `git add <path> …`, not `git add -A` or `git add .`, so unrelated edits and scratch files stay out. Leave the other concerns unstaged for their own commits.
+
+## Write the message
+
+Conventional Commits: `<type>(<scope>): <subject>`. The type is one of `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, or `revert` — pick the one the change earns. The `(<scope>)` is optional; add it only when it sharpens the subject. Subject in the imperative, ≤50 characters. Add a body, wrapped at 72, only when the diff doesn't explain its own why.
+
+Breaking an API? Mark it: `!` before the colon (`feat!:`), or a `BREAKING CHANGE: <what broke>` footer — the mark SemVer and changelog tools read for a major bump.
+
+## Commit and loop
+
+Review the staged diff one more time, then commit. Changes still uncommitted? Back to **Stage one concern** for the next.
+
+Done when the tree is clean and every commit is one logical change in Conventional Commits form.

package/skills/commit/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Commit"
+  short_description: "Commit changes as small Conventional Commits"
+
+policy:
+  allow_implicit_invocation: false

package/skills/cut-branch/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: cut-branch
+description: Cut a git branch for an issue, named from the issue's type and title.
+argument-hint: "[issue-id]"
+disable-model-invocation: true
+---
+
+Cut a working branch for one issue and check it out. Git only — planning or implementation marks work started per [`references/issue-tracker.md`](../../references/issue-tracker.md).
+
+Resolve the tracker per [`references/issue-tracker.md`](../../references/issue-tracker.md).
+
+## Name the branch
+
+1. Take the issue from the argument — an id or URL. With no argument, use the issue under discussion. Read its title and type from the tracker.
+2. Pick the conventional type from the issue itself: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, or `chore`. Derive it from the issue's own type field or labels; ask the user only when the issue gives no signal.
+3. Build `<type>/<issue-id>-<slug>`, where `slug` condenses the issue to ≤7 words, lowercased and hyphen-separated, e.g. `feat/42-add-meaning-to-universe`.
+
+## Cut it
+
+4. `git checkout -b <branch-name>` — it forks from the current branch, so cut from the branch you mean to base the work on.
+
+Done when the branch exists and is checked out.

package/skills/cut-branch/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Cut Branch"
+  short_description: "Create an issue-named working branch"
+
+policy:
+  allow_implicit_invocation: false

package/skills/fetch-issues/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: fetch-issues
+description: List your open issues on this project's tracker so you can pick one to work on.
+disable-model-invocation: true
+---
+
+List every open issue assigned to the user that is still **active** — workable, not yet done. Read-only: list them and stop.
+
+Resolve the tracker and the user's identity per [`references/issue-tracker.md`](../../references/issue-tracker.md).
+
+## Fetch and filter
+
+Fetch the open issues assigned to the user, then keep only the **active** ones. Read the active set from `active_states` in `.agents/config.yml`. When that key is absent, treat every state that is not closed, done, or a QA/verification stage as active.
+
+## Show them
+
+For each surviving issue print one row: id, title, a one-line summary, and its current state or labels, then stop. Picking an issue and starting on it is `cut-branch`'s job.

package/skills/fetch-issues/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Fetch Issues"
+  short_description: "List your active assigned issues"
+
+policy:
+  allow_implicit_invocation: false

package/skills/help-me-understand/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: help-me-understand
+description: Explain how a feature, pipeline, workflow, or concept in this codebase actually works.
+argument-hint: "What do you want to understand?"
+disable-model-invocation: true
+---
+
+Explain how something in this codebase works, to someone who has never worked in it. Comprehension is the deliverable — measured by what the user can restate afterwards, not by how much you covered. Answer in chat; write a file only if they ask for one.
+
+If the argument names an audience (`for a PM`, `for a non-engineer`), take your vocabulary and depth from it. Otherwise, an engineer new to this codebase.
+
+## Trace first
+
+Read the real path before writing a word — entry point to exit, in the actual code. Names lie, and so does parametric knowledge of how a thing "usually" works. Done when you can name every **hop** with a `file:line` and say what that hop decides.
+
+## Size it
+
+Count the hops the user must hold in their head at once.
+
+- **One answer** if the mechanism fits in ~200 words plus one snippet, with no forward references.
+- **Rounds** otherwise. The forward reference is the tell: if explaining hop 1 needs "more on that later", it's rounds.
+
+## Open with the map
+
+Both branches start here, in five lines or fewer: one sentence on what the thing is for, then the whole path as an arrow chain.
+
+```
+🗺 The universe module: question → normalize → cache lookup → compute → return 42. 5 hops.
+```
+
+In rounds mode the hop count is a contract — the user knows how far this goes.
+
+## One answer
+
+Map, the mechanism in your own words, one snippet of the lines that make the decision, and the one thing that would surprise someone reading the code cold. Stop there.
+
+## Rounds
+
+One hop per round, then wait for the user.
+
+```
+**Hop 3/5 — Cache lookup**
+
+<2–4 sentences: what this hop does, in your own words>
+
+<≤10 lines of code — the lines that make the decision, rest elided with `…`>
+
+<one line: what breaks if this hop is removed>
+
+❓ <checkpoint question>
+```
+
+The code is evidence, not the explanation. If the prose only works with the snippet in front of it, the prose isn't doing its job yet.
+
+A checkpoint asks the user to predict or apply — "a repeat question comes straight back from the cache; what happens the first time one is asked?" — an answer only comprehension produces. Wrong or hedged: re-explain that hop from a different angle before moving on. A question back from them means the round landed — answer it, then resume.
+
+They say skip, or name a hop: jump there.
+
+## Recap
+
+After the last hop, the whole thing in eight lines or fewer: the map again, each hop annotated with what it decides. This is the part they keep.

package/skills/help-me-understand/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Help Me Understand"
+  short_description: "Explain how this codebase actually works"
+
+policy:
+  allow_implicit_invocation: false

package/skills/implement-change/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: implement-change
+description: Implement a change from a saved plan or clear issue requirements, verify it, and leave it uncommitted for review.
+argument-hint: "[issue-id]"
+disable-model-invocation: true
+---
+
+Implement the change and match how the repo already builds and tests. Stop when the change is built and verified — reviewing the diff and committing are the user's next move, on separate skills.
+
+## Locate
+
+Take the issue from the argument, else the current branch, else the issue under discussion. Resolve the tracker per [`references/issue-tracker.md`](../../references/issue-tracker.md) and read the issue's title and body alongside the user's context.
+
+Look for an existing workspace per [`references/issue-workspace.md`](../../references/issue-workspace.md). Read `PLAN.md` and `CONTEXT.md` when present, then inspect the affected code and its callers.
+
+## Choose the path
+
+- **Saved plan** → follow its acceptance criteria and open tasks.
+- **No saved plan** → proceed directly when the intended behavior, affected scope, and verification are clear. State those briefly in the conversation; keep this path free of plan and workspace creation.
+
+If investigation reveals an unresolved product or design decision, explain the decision and pause dependent implementation. Point the user to `/plan-implementation`, or `/update-plan` when revising an existing plan. Routine implementation details are yours to resolve.
+
+## Build
+
+Before writing code, move the issue to `states.in_progress` per **Moving an issue's state** in [`references/issue-tracker.md`](../../references/issue-tracker.md). When a plan exists, move its Status to `In Progress`, work its open tasks top to bottom, and check off each as it lands. Otherwise implement against the issue's requirements.
+
+Read the repo's test posture first:
+
+- **Repo already tests** → drive `/tdd` at the seams.
+- **Repo has no tests** → write code only; don't stand up a test harness it never asked for.
+
+Comment like the repo does; where it gives no signal, default to none. Add one only when the WHY resists the code (a constraint, a workaround, a surprise), never to restate code or name the task or issue.
+
+## Hand off
+
+Verify the change against the plan's acceptance criteria or the issue's requirements: it runs, and its tests (if any) pass. Report what changed, the verification performed, and any remaining limitations. Leave any plan's Status at `In Progress`, write no commit, and open no MR. The user will then review the diff — by hand and/or via `/code-review` — before running `/commit`.
+
+Done when the requirements are met, every task in an existing plan is checked off, the change is verified, and it sits uncommitted for the user to review.

package/skills/implement-change/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Implement Change"
+  short_description: "Build and verify a planned or clear change"
+
+policy:
+  allow_implicit_invocation: false

package/skills/open-change-request/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: open-change-request
+description: Open a merge/pull request for the current branch and move its issue to review.
+argument-hint: "[issue-id]"
+disable-model-invocation: true
+---
+
+Open the change request for the current branch — the merge request or pull request your tracker calls it — then move its issue to the review state so the board shows the code is ready.
+
+Resolve the tracker and the user's identity per [`references/issue-tracker.md`](../../references/issue-tracker.md). Read the noun your tracker gives the artifact from `change_request` in `.agents/config.yml` — MR on GitLab, PR on GitHub — and call it that in every message.
+
+## Open it
+
+1. Find the issue for the current branch. `cut-branch` named the branch `<type>/<issue-id>-<slug>`, so its id lives in the branch name; fall back to the argument, then to the issue under discussion. Push the branch to the remote if it is not there yet.
+2. Open the change request from the current branch against the repo's default branch. Reference the issue with `Refs #<id>` (or your tracker's link form — a reference, not an auto-close keyword). The change request already shows the commits and the full diff, so the body adds only what those can't:
+   - Summary — what the change does, and why when that isn't obvious. 1-4 sentences.
+   - Config (optional) — new environment variables, feature flags, or config files.
+   - Notes (optional) — what the diff and commits don't reveal: a renamed concept, a chosen tradeoff, a subtlety.
+3. Title it `Type: Capitalized description` — the conventional type capitalized, then the issue's own title, e.g. `Feat: Add meaning to the universe module`. Leave the scope out unless the title is unclear without it.
+4. Assign it to the user.
+
+## Mark it
+
+5. Move the issue to `states.review`, following **Moving an issue's state** in [`references/issue-tracker.md`](../../references/issue-tracker.md).
+
+Done when the change request is open against the default branch, assigned to the user, and its issue reads as in review on the tracker.

package/skills/open-change-request/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Open Change Request"
+  short_description: "Open a pull or merge request"
+
+policy:
+  allow_implicit_invocation: false

package/skills/plan-implementation/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: plan-implementation
+description: Plan a pulled issue with the user and save the plan locally so any session can resume it.
+argument-hint: "[issue-id] [context]"
+disable-model-invocation: true
+---
+
+Turn a pulled issue into a concrete, stepped plan, and save it where the next session can pick it up. Plan only: write no source files until the user confirms or runs `/implement-change`. The plan and context files are the only files you write here.
+
+Resolve the tracker per [`references/issue-tracker.md`](../../references/issue-tracker.md).
+
+## Gather
+
+Take the issue from the argument or the one under discussion, and read its title and body. Picking it up to plan is where work starts, so move it to `states.in_progress` per **Moving an issue's state** in [`references/issue-tracker.md`](../../references/issue-tracker.md). It may be thin, so pull in the out-of-band context the user gives you. The plan is what you synthesize from it.
+
+When the issue and that context still leave the work under-decided — a real decision hasn't been made yet, not just a detail to clarify — grill it out with `/grilling` first, then plan.
+
+## Discuss
+
+Viability first: is this worth doing, and doable as framed? If not, surface that with the user before planning further. If it's really several issues wearing one, break it up with `/to-tickets` before planning.
+
+Close the gaps between the issue and a concrete plan. Work these through with the user before writing the plan:
+
+- Acceptance criteria — the observable outcomes that mark the issue complete.
+- Architecture and its tradeoffs.
+- Libraries and tools — check the library's official docs for current conventions (using Context7 MCP when available) before proposing one.
+- Blast radius — which parts of the codebase change, and what that ripples into.
+
+Resolve uncertainties that could change scope, approach, or correctness using available evidence, then ask the user for remaining decisions. Discussion is complete when each identified uncertainty is resolved or has an explicit verification task before work that depends on it.
+
+## Save
+
+Store the plan in the issue workspace — the `.issues/<issue-id>-<slug>/` layout, the `PLAN.md` template, and the `CONTEXT.md` companion — per [`references/issue-workspace.md`](../../references/issue-workspace.md).
+
+- Write the synthesized plan to `PLAN.md`.
+- When context beyond the issue itself surfaced, capture it in `CONTEXT.md`.
+- Print the path after writing.
+- On later iterations, edit `PLAN.md` in place rather than adding a second copy.

package/skills/plan-implementation/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Plan Implementation"
+  short_description: "Turn an issue into a resumable local plan"
+
+policy:
+  allow_implicit_invocation: false

package/skills/setup-agency-skills/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: setup-agency-skills
+description: Configure `.agents/config.yml` — the tracker and workflow states the other agency skills read. Run once per project, before the rest.
+disable-model-invocation: true
+---
+
+Write `.agents/config.yml` so the other agency skills resolve your tracker and move issues into states that actually exist on your board. Run once per project. Re-run to revise: read the existing config first and edit it, rather than starting over.
+
+Detect and derive first; ask the user only for what the environment can't reveal. Every state you record must be **detected from the board, never invented**: the runtime skills only set a state that already exists, so a value the board doesn't have silently no-ops.
+
+## Resolve the tracker
+
+Resolve the tracker and the user's identity per [`references/issue-tracker.md`](../../references/issue-tracker.md). This names the host and confirms you can reach the board.
+
+- **Remote names the tracker** (GitHub, GitLab) → leave `tracker` and `project` out of the config; the skills read them from `git remote` every run. Writing them caches a lookup that can go stale.
+- **Remote can't name it** (Jira, Linear, self-hosted) → ask the user for `tracker` and `project`, and write both.
+
+## Read the board
+
+Fetch the workflow states the board actually uses: the status field's values, or the workflow labels when the tracker models state as labels. This live set is the point of running setup. It's what a static example can't know, and what every state you write must match.
+
+## Map the states
+
+Fill three keys from the real board states, offering the closest match for each and confirming it with the user:
+
+- `states.in_progress`: the state that means **work has started** (e.g. `WIP`, `In Progress`).
+- `states.review`: the state that means **code is ready for review** (e.g. `In Review`, `Dev Review`).
+- `active_states`: the states that count as **workable, not done**. Default to every state that isn't closed, done, or a QA/verification stage, and confirm.
+
+When the board has no state matching a key, leave the key out; the skills skip that move rather than guess.
+
+Set `change_request` automatically from the tracker: `MR` on GitLab, `PR` on GitHub or Bitbucket.
+
+## Write and validate
+
+Write `.agents/config.yml` in the project root, following the shape of [`config.example.yml`](../../config.example.yml). Keep only the keys this project needs. Omit `tracker` and `project` when the remote resolves them. Print the path.

package/skills/setup-agency-skills/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Setup Agency Skills"
+  short_description: "Configure the tracker and workflow states"
+
+policy:
+  allow_implicit_invocation: false

package/skills/update-plan/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: update-plan
+description: Re-synthesize a saved plan after new context arrived, keeping completed work intact.
+argument-hint: "[issue-id] [context]"
+disable-model-invocation: true
+---
+
+Fold new context into a plan that already exists — re-synthesize `PLAN.md`, show the user the delta, and leave finished work finished. Plan only: write no source files.
+
+## Locate
+
+Find the issue workspace per [`references/issue-workspace.md`](../../references/issue-workspace.md), then read its `PLAN.md` and `CONTEXT.md`. You are revising them, not starting over. No workspace for this issue means it was never planned; send the user to `/plan-implementation`.
+
+## Gather
+
+Append the new context, from the argument or the conversation, to `CONTEXT.md`. Create it if the first plan skipped it.
+
+When the new context leaves a real decision open — not just a detail — grill it out with `/grilling` before re-synthesizing.
+
+## Re-synthesize
+
+Rebuild `PLAN.md` from the issue plus the grown `CONTEXT.md`, using the issue workspace template and recording rules. Two things hold fixed:
+
+- **Completed tasks stay done.** A `[x]` task keeps its check unless the new context explicitly undoes it.
+- **Status stays where it was** (`Planned` / `In Progress`), unless the new context moves it.
+
+## Confirm and save
+
+Before writing, show the user the delta — the sections that moved and why the new context drove each. On their confirmation, write the revised plan to `PLAN.md` in place; never add a second copy. Print the path.
+
+Done when `PLAN.md` reflects the new context, completed tasks are intact, the user has confirmed the delta, and no source file was touched.

package/skills/update-plan/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Update Plan"
+  short_description: "Re-synthesize a plan from new context"
+
+policy:
+  allow_implicit_invocation: false

package/skills/where-were-we/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: where-were-we
+description: Re-orient on an in-flight issue from its requirements, Git history, and any saved plan, and name the next command.
+argument-hint: "[issue-id]"
+disable-model-invocation: true
+---
+
+Reconstruct where an issue's work stands after time away, and name the one command that moves it forward.
+Read-only: gather the state and report it, change nothing.
+
+## Locate
+
+Resolve the issue from the argument, else the current branch, else the issue under discussion. Look for its workspace per [`references/issue-workspace.md`](../../references/issue-workspace.md) and read `PLAN.md` and `CONTEXT.md` when present. With no saved plan, reconstruct progress from the issue and Git.
+
+## Reconstruct
+
+Read the trail the pipeline leaves, across three places:
+
+- **Plan, when present** — `PLAN.md`'s status, acceptance criteria, and which tasks are checked versus open. `CONTEXT.md` for the decisions behind them.
+- **Git** — the current branch, the commits already on it, and any uncommitted changes (`git status`, `git diff`).
+- **Tracker** — the issue's title, requirements, state, and whether a change request is already open, per [`references/issue-tracker.md`](../../references/issue-tracker.md).
+
+Without a plan, compare the branch's changes with the issue's requirements. Distinguish implemented behavior from verified behavior; commits alone do not prove completion.
+
+## Brief
+
+Report in this shape:
+
+- **Issue** — one line: id, title, why it exists.
+- **Done** — completed requirements or checked plan tasks, with supporting changes and verification evidence.
+- **Left** — remaining requirements or open plan tasks, missing verification, and any uncommitted work sitting in the tree.
+- **Next** — the single command that advances it, read from where the trail stops:
+  - Change request already open → it's in review; nothing to run.
+  - Otherwise, work remains or completion is uncertain → `/implement-change` resumes implementation or verification.
+  - Work complete and verified, uncommitted diff in the tree → review the diff, then `/commit`.
+  - Work complete, verified, and committed, no change request open → `/open-change-request`.

package/skills/where-were-we/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Where Were We"
+  short_description: "Reconstruct progress and name the next step"
+
+policy:
+  allow_implicit_invocation: false