@homericintelligence/athena-opencode 0.4.4

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Micah Villmow
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/NOTICE

@@ -0,0 +1,22 @@
+Athena
+Copyright (c) HomericIntelligence contributors. All rights reserved.
+
+Athena is distributed under BSD-3-Clause. See LICENSE.
+
+Required repositories
+---------------------
+
+Athena resolves Mnemosyne for knowledge and Hephaestus for automation. Their contents are cloned
+and used separately under their own licenses; they are not copied into Athena's plugin archive.
+
+Third-party skill attribution
+-----------------------------
+
+Several skills are adapted from obra/superpowers under the MIT License. The mapping, copyright,
+source, and full license text are preserved in skills/THIRD_PARTY_LICENSES.md.
+
+Trademarks
+----------
+
+"HomericIntelligence", "Athena", "Mnemosyne", "Hephaestus", and "Myrmidons" identify their
+respective projects or themes and are not claims of endorsement by third parties.

package/README.md

@@ -0,0 +1,45 @@
+# athena-opencode
+
+[Athena](https://github.com/HomericIntelligence/Athena) workflow skills packaged as an
+[opencode](https://opencode.ai) plugin. Installing this plugin places the full canonical skill
+corpus under your opencode configuration directory, where opencode discovers and loads it natively.
+
+## Install
+
+Add the package to the `plugin` array of your opencode configuration
+(`~/.config/opencode/opencode.json` or a project `opencode.json`):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@homericintelligence/athena-opencode"]
+}
+```
+
+Quit and restart opencode. On startup the plugin copies the bundled `skills/` corpus to:
+
+```
+$XDG_CONFIG_HOME/opencode/skills/athena/
+```
+
+(`~/.config/opencode/skills/athena/` by default.) The plugin only ever writes inside that
+`athena/` namespace; other skills in your configuration are never touched. Each restart refreshes
+the namespace to match the installed plugin version, so upgrading the npm package upgrades the
+skills.
+
+## Use
+
+Invoke skills through opencode's native skill mechanism, for example by asking opencode to use the
+`repo-review`, `pr-review`, or `plan-issue` skill. See the root
+[`README.md`](https://github.com/HomericIntelligence/Athena#readme) for the full skill catalog,
+dependency requirements (Git, Python 3.13, authenticated `gh` for forge routes), and capability
+fallbacks.
+
+## Uninstall
+
+Remove `"@homericintelligence/athena-opencode"` from the `plugin` array, restart opencode, and delete
+`opencode/skills/athena/` from your configuration directory if you want the files gone immediately.
+
+## License
+
+BSD-3-Clause. See `LICENSE` and `NOTICE`.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@homericintelligence/athena-opencode",
+  "version": "0.4.4",
+  "description": "Athena workflow skills packaged as an opencode plugin.",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "main": "plugin.js",
+  "files": [
+    "plugin.js",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HomericIntelligence/Athena"
+  },
+  "homepage": "https://github.com/HomericIntelligence/Athena",
+  "bugs": "https://github.com/HomericIntelligence/Athena/issues",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "athena",
+    "agents",
+    "skills"
+  ],
+  "private": false
+}

package/plugin.js

@@ -0,0 +1,54 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const NAMESPACE = "athena";
+
+function bundledSkillsRoot() {
+  return fileURLToPath(new URL("./skills/", import.meta.url));
+}
+
+function configBase() {
+  const override = process.env.XDG_CONFIG_HOME;
+  if (override !== undefined && override !== "") {
+    return resolve(override);
+  }
+  return join(homedir(), ".config");
+}
+
+function installTarget() {
+  return join(configBase(), "opencode", "skills", NAMESPACE);
+}
+
+export function syncSkills() {
+  const source = bundledSkillsRoot();
+  const target = installTarget();
+  if (!existsSync(join(source, "_cli.py"))) {
+    throw new Error(
+      `Athena skill corpus is missing next to plugin.js: ${source}`,
+    );
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  rmSync(target, { recursive: true, force: true });
+  cpSync(source, target, { recursive: true });
+  return target;
+}
+
+async function athenaPlugin() {
+  try {
+    syncSkills();
+  } catch (error) {
+    console.warn(`[athena-opencode] skill installation failed: ${error}`);
+  }
+  return {};
+}
+
+export default athenaPlugin;
+
+export function bundledSkillNames() {
+  return readdirSync(bundledSkillsRoot(), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}

package/skills/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,50 @@
+# Third-Party Licenses
+
+## obra/superpowers
+
+Several skills in this directory were adapted from [obra/superpowers](https://github.com/obra/superpowers),
+a Claude Code skills framework by Jesse Vincent / Prime Radiant.
+
+**Source repository:** <https://github.com/obra/superpowers>
+**License:** MIT License
+**Copyright:** Copyright (c) 2025 Jesse Vincent
+
+### Derived Skills
+
+The following skills were adapted from obra/superpowers source material:
+
+| Athena Skill | Source Skill(s) |
+| --- | --- |
+| `test-driven-development` | `skills/test-driven-development/SKILL.md` |
+| `systematic-debugging` | `skills/systematic-debugging/SKILL.md` |
+| `git-worktrees` | `skills/using-git-worktrees/SKILL.md` |
+| `brainstorm` | `skills/brainstorming/SKILL.md` |
+
+Each derived skill has been modified for Athena's host-neutral invocation, local policy, mandatory
+knowledge workflow, and Greek-themed orchestration.
+
+---
+
+### Full MIT License Text
+
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+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/skills/_cli.py

@@ -0,0 +1,152 @@
+"""Shared argparse construction for Athena's executable helpers."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+PLUGIN_ROOT = Path(__file__).resolve().parent.parent
+
+
+def run_command(
+    arguments: Sequence[str], **kwargs: Any
+) -> subprocess.CompletedProcess[str]:
+    """Run an external command or identify a missing required capability."""
+    if not arguments:
+        raise RuntimeError("required command is empty")
+    try:
+        check = kwargs.pop("check", False)
+        return subprocess.run(arguments, check=check, **kwargs)
+    except FileNotFoundError as error:
+        command = error.filename or arguments[0]
+        raise RuntimeError(f"required command unavailable: {command}") from error
+
+
+def git_read_environment() -> dict[str, str]:
+    """Return a hermetic environment for immutable, non-interactive Git reads."""
+    environment = {
+        key: value for key, value in os.environ.items() if not key.startswith("GIT_")
+    }
+    # `--no-replace-objects` does not disable deprecated graft files. Force Git
+    # to read an empty graft source. Strip every inherited GIT_* setting first:
+    # location, object, index, config, attribute, pathspec, and transport
+    # overrides can otherwise redirect or change a supposedly immutable read.
+    environment.update(
+        {
+            "GIT_ATTR_NOSYSTEM": "1",
+            "GIT_CONFIG_GLOBAL": os.devnull,
+            "GIT_CONFIG_NOSYSTEM": "1",
+            "GIT_CONFIG_SYSTEM": os.devnull,
+            "GIT_GRAFT_FILE": os.devnull,
+            "GIT_NO_LAZY_FETCH": "1",
+            "GIT_NO_REPLACE_OBJECTS": "1",
+            "GIT_OPTIONAL_LOCKS": "0",
+            "GIT_TERMINAL_PROMPT": "0",
+        }
+    )
+    return environment
+
+
+def git_read_arguments() -> tuple[str, ...]:
+    """Return Git options that disable mutable local object-graph metadata."""
+    return ("-c", "core.commitGraph=false", "--no-replace-objects")
+
+
+def require_complete_git_history(*, cwd: Path | None = None) -> None:
+    """Reject shallow history before deriving immutable ancestry evidence."""
+    result = run_command(
+        ["git", *git_read_arguments(), "rev-parse", "--is-shallow-repository"],
+        capture_output=True,
+        cwd=cwd,
+        env=git_read_environment(),
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        message = (
+            result.stderr.strip() or "git rev-parse --is-shallow-repository failed"
+        )
+        raise RuntimeError(message)
+    if result.stdout.strip() != "false":
+        raise RuntimeError(
+            "immutable review evidence requires a non-shallow repository; "
+            "use a complete source snapshot"
+        )
+
+
+def require_unambiguous_git_merge_base(
+    base_oid: str, head_oid: str, *, cwd: Path | None = None
+) -> str:
+    """Return the sole immutable merge base or reject ambiguous topology."""
+    result = run_command(
+        [
+            "git",
+            *git_read_arguments(),
+            "merge-base",
+            "--all",
+            base_oid,
+            head_oid,
+        ],
+        capture_output=True,
+        cwd=cwd,
+        env=git_read_environment(),
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        message = result.stderr.strip() or "git merge-base failed"
+        raise RuntimeError(message)
+    merge_bases = result.stdout.splitlines()
+    if len(merge_bases) != 1 or not merge_bases[0]:
+        raise RuntimeError(
+            "immutable review evidence requires one unambiguous merge base"
+        )
+    return merge_bases[0]
+
+
+def plugin_version() -> str:
+    """Return the version from the canonical Codex plugin manifest."""
+    manifest = PLUGIN_ROOT / ".codex-plugin" / "plugin.json"
+    document = json.loads(manifest.read_text(encoding="utf-8"))
+    version = document.get("version") if isinstance(document, dict) else None
+    if not isinstance(version, str):
+        raise TypeError(f"plugin manifest has no string version: {manifest}")
+    return version
+
+
+class _PluginVersionAction(argparse.Action):
+    """Resolve the plugin version only when the option is requested."""
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: str | Sequence[Any] | None,
+        option_string: str | None = None,
+    ) -> None:
+        del namespace, values, option_string
+        try:
+            version = plugin_version()
+        except (OSError, TypeError, json.JSONDecodeError) as error:
+            parser.exit(
+                1, f"{parser.prog}: error: cannot read plugin version: {error}\n"
+            )
+        print(f"{parser.prog} {version}")
+        parser.exit(0)
+
+
+def argument_parser(*, description: str | None = None) -> argparse.ArgumentParser:
+    """Create the required parser with a consistent plugin-version action."""
+    parser = argparse.ArgumentParser(description=description)
+    parser.add_argument(
+        "--version",
+        action=_PluginVersionAction,
+        nargs=0,
+        help="show the Athena plugin version and exit",
+    )
+    return parser

package/skills/advise/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: advise
+license: BSD-3-Clause
+description: Retrieve trusted Mnemosyne guidance before unfamiliar planning or implementation. In planning mode, use the checked-out knowledge tree as a best effort without requiring upstream synchronization; report its revision and any trust or freshness limits.
+argument-hint: <task description>
+allowed-tools: [Read, Bash, Grep, Glob]
+---
+
+# Advise
+
+Why: decisions are only as reliable as the current, trusted knowledge behind them.
+
+## Required knowledge gate
+
+Prepare Mnemosyne at `$HOME/.agent_brain/knowledge` under the canonical
+[`dependency-resolution` contract](../../docs/dependency-resolution.md). Report the resolved
+repository, commit SHA, and trust basis. Outside planning mode, resolution, authentication,
+checkout, update, or revalidation failure blocks this skill.
+
+**Planning mode:** before searching, framing options, drafting a plan, or relying on remembered
+guidance, inspect the existing knowledge checkout and bind retrieval to its current `HEAD` when
+available. Do not require upstream resolution, fetch, fast-forward, or automatic-fork
+revalidation. Use the checked-out content as a best effort, and report its repository, current
+commit SHA, origin/trust status, and any freshness or verification limitation. A missing checkout
+or failed inspection is a limitation to report, not a reason to stop the primary plan; return an
+explicit `no applicable durable guidance` result and do not continue retrieval as if knowledge were
+available. Never substitute a different repository or silently treat local content as current or
+trusted.
+
+## Retrieve
+
+- Resolve this installed skill's directory and run its
+  `scripts/list_retrievable_skills.py <knowledge-root>` helper by absolute path. Treat only the
+  returned flat main-skill paths as retrieval candidates; the helper excludes notes, history, and
+  nested artifacts through the same executable contract used by `learn`. Do not replace a failed
+  helper with an ad hoc glob: outside planning mode, report the capability failure and stop; in
+  planning mode, report `no applicable durable guidance` and the limitation.
+- Search the returned files' names, descriptions, categories, tags, triggers, failed attempts, and
+  results; use notes only after selecting a main skill that links them, and use Git and PR history
+  as provenance.
+- Rank by intended outcome, constraints, and failure mode before title or wording. Read at most five
+  selected entries completely, preferring newer and better-verified guidance.
+- For each result, state its version, verification, concrete relevance, non-relevance boundary,
+  contradictions, and failed approaches; clearly label unverified guidance.
+- Surface potentially matching open Mnemosyne PRs by candidate artifact or title and report their
+  branch and URL. This is a retrieval hint, not duplicate clearance: `learn` must inspect the changed
+  content of every open PR semantically before any write.
+
+## Recommend
+
+Treat intent as trigger/context plus desired outcome, not session wording, names, or issue numbers.
+Prefer one canonical entry per intent; search history before proposing a name that may have been
+consolidated. Route repository audits to `repo-review`, PR audits to `pr-review`, and vary review
+depth by mode. Recommend `learn` only for a verified new trigger, corrected command or parameter,
+failure mode, or workflow.
+
+## Output
+
+Return the resolved `owner/Mnemosyne` revision, the bound local checkout `HEAD`, or an explicit
+no-local-guidance status, together with a table of entry, version, verification, relevance, and
+boundary. Include contradictions, what worked or failed, copy-ready parameters, and clearly label
+best-effort or unverified guidance.

package/skills/advise/scripts/list_retrievable_skills.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""List flat Mnemosyne main-skill files eligible for normal retrieval."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+if __package__ in {None, ""}:
+    sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+
+from skills._cli import argument_parser
+
+COMPANION_FILE = re.compile(
+    r"(?:.*\.notes(?:-[A-Za-z0-9_-]+)?\.md|.*\.history(?:[-.].*)?)\Z"
+)
+
+
+def retrievable_skill_files(knowledge_root: Path) -> list[Path]:
+    """Return sorted flat main-skill files from a Mnemosyne checkout."""
+    skills_directory = knowledge_root / "skills"
+    if not skills_directory.is_dir():
+        raise RuntimeError(
+            f"knowledge skills directory is unavailable: {skills_directory}"
+        )
+    return sorted(
+        path
+        for path in skills_directory.glob("*.md")
+        if path.is_file() and COMPANION_FILE.fullmatch(path.name) is None
+    )
+
+
+def main() -> int:
+    parser = argument_parser(description=__doc__)
+    parser.add_argument("knowledge_root", type=Path)
+    arguments = parser.parse_args()
+    try:
+        paths = retrievable_skill_files(arguments.knowledge_root)
+    except RuntimeError as error:
+        print(error, file=sys.stderr)
+        return 1
+    for path in paths:
+        print(path.relative_to(arguments.knowledge_root).as_posix())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: brainstorm
+license: BSD-3-Clause
+description: Use before complex creative work to explore intent and requirements. Requires the Mnemosyne knowledge backend through advise and fails closed when it cannot be prepared.
+argument-hint: <idea or feature description>
+allowed-tools: [Read, Write, Bash, Grep, Glob, Agent]
+---
+
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and proceed with the requested implementation unless a requirement remains unresolved.
+
+**DESIGN CHECKPOINT:** Present a scaled design before complex implementation. It is a shared understanding checkpoint, not a permission gate; pause only for unresolved requirements or a filesystem-destructive action.
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every feature goes through this process. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences), and should make assumptions and constraints visible before implementation.
+
+## Checklist
+
+Complete in order:
+
+1. **Run `advise`** with the feature description to check the required knowledge backend.
+2. **Explore project context** — check files, docs, recent commits
+3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+4. **Propose 2-3 approaches** — with trade-offs and your recommendation
+5. **Present design** — in sections scaled to their complexity; ask only to resolve material ambiguity
+6. **Persist when needed** — write `docs/specs/YYYY-MM-DD-<topic>-design.md` only when complexity,
+   project policy, or a current downstream consumer requires a durable specification
+7. **Design self-review** — scan for placeholders, contradictions, ambiguity, and scope issues
+8. **User confirms the design** — request file review only when a specification was persisted
+9. **Transition to implementation** — invoke `myrmidon-swarm` for complex implementation. If an
+   installed planning skill is available, it may track the approved design; otherwise write a short
+   numbered implementation plan in the current conversation and proceed sequentially.
+
+## The Process
+
+**Understanding the idea:**
+
+- Check out the current project state first (files, docs, `git log --oneline -10`)
+- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems, flag this immediately. Help the user decompose into sub-projects first.
+- For appropriately-scoped projects, ask questions one at a time
+- Prefer multiple choice questions when possible
+- Only one question per message
+- Focus on: purpose, constraints, success criteria
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+- Lead with your recommended option and explain why
+- Reference existing patterns in the target codebase
+
+**Presenting the design:**
+
+- Present in sections, ask after each whether it looks right
+- Scale each section to its complexity
+- Cover: architecture, components, data flow, error handling, testing strategy
+- Follow Athena's local development principles: KISS, YAGNI, DRY, SOLID, modularity, and POLA
+
+**Working in existing codebases:**
+
+- Follow existing patterns in the target repository
+- Invoke the `advise` skill first to check for existing implementations
+- Don't propose unrelated refactoring — stay focused on the current goal
+
+## After the Design
+
+**Persist a spec only when required:**
+
+For small changes, keep the approved design in the conversation and proceed. When complexity,
+project policy, or a current downstream consumer requires a durable specification, save it to
+`docs/specs/YYYY-MM-DD-<topic>-design.md` and commit it as
+`docs(specs): add <topic> design document`.
+
+Before writing or committing a specification, read the target repository's mutation, signing, DCO,
+and review policy. A specification that is in scope may be written and committed without a separate
+approval prompt; retain it in the conversation when a durable artifact is not needed.
+
+**Spec Self-Review:**
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections? Fix them.
+2. **Internal consistency:** Do any sections contradict each other?
+3. **Scope check:** Is this focused enough for a single plan?
+4. **Ambiguity check:** Can any requirement be interpreted two ways? Pick one and make it explicit.
+
+**User Review:**
+After self-review of a persisted specification, report its location and proceed with the requested
+implementation unless the user requests changes:
+> "Spec written and committed to `docs/specs/<filename>`. Please review and let me know if you want changes before we start planning implementation."
+
+
+**Implementation:**
+
+- Use an installed planning skill for task tracking, or write the numbered plan inline when none is
+  installed.
+- Invoke the `myrmidon-swarm` skill for complex multi-agent work.
+
+## Key Principles
+
+- **One question at a time** — don't overwhelm with multiple questions
+- **YAGNI ruthlessly** — remove unnecessary features from all designs
+- **Explore alternatives** — always propose 2-3 approaches
+- **Incremental validation** — present design sections and resolve material ambiguity before moving on
+- **Invoke `advise` first** — don't propose what's already been built or debugged
+
+---
+
+_Adapted from [obra/superpowers](https://github.com/obra/superpowers) under the [MIT License](https://github.com/obra/superpowers/blob/main/LICENSE). Copyright (c) 2025 Jesse Vincent._

package/skills/change-review/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: change-review
+license: BSD-3-Clause
+description: Review only the working-tree, staged, or explicit-range changes for architecture alignment, behavior, language practices, and evidence. Use before committing or opening a PR; it never edits source or posts forge comments.
+argument-hint: "[--worktree | --staged | --range BASE..HEAD] [PATH ...]"
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Change review
+
+Why: bind the exact local change before review so findings apply to the bytes
+that will be committed.
+
+Use the shared [review contract](../../docs/review/common.md),
+[language routing](../../docs/review/language-routing.md), and
+[behavior-first testing](../../docs/review/behavior-first-testing.md).
+
+This skill is read-only. It never edits source, stages files, creates Git
+state, posts forge content, opens issues, or writes review notes into source.
+
+## Bind the scope
+
+Choose exactly one scope:
+
+- `--worktree` (default): tracked differences from `HEAD` and non-ignored
+  untracked files;
+- `--staged`: index changes from `HEAD`; or
+- `--range BASE..HEAD`: the explicit Git range.
+
+Resolve the installed [`scripts/resolve_scope.py`](scripts/resolve_scope.py)
+from this skill directory before inspection. Read every eligible object in its
+manifest and follow the [scope-resolution safety contract](references/scope-resolution.md).
+Paths further restrict the selected diff and must remain inside the repository
+root.
+
+For a range, report immutable base and head commits. For worktree or staged
+scope, report `HEAD`, selected paths, and the returned content-bound digest;
+never create a commit, tree, stash, temporary index, or other Git state to
+invent a head. Report an empty scope and never silently substitute a different
+range.
+
+`--staged` and `--range` exclude untracked worktree files. State that boundary
+in the result. If resolution cannot safely cover the selected scope, report the
+coverage gap and narrow the paths or choose a safer scope; never sample it.
+
+## Review and deliver
+
+Follow the shared review flow: establish architecture first, classify only
+applicable surfaces and language profiles, inspect changed behavior and tests,
+then de-duplicate severity-ranked evidence. Record each skipped check as N/A
+with its reason.
+
+For a material architecture change, require a stated design decision, ADR, or
+[design record](../../docs/review/design-docs.md). Missing architecture evidence
+is a blocker; do not invent it.
+
+Return in the console or host-native read-only annotation surface:
+
+1. scope identity, base/head or manifest digest, and files read;
+2. architecture decision first, then applicable and N/A checks;
+3. severity-ranked findings with exact `path:line`, impact, evidence, and a
+   proportionate remediation direction;
+4. behavior-first testing and validation coverage; and
+5. residual risks and unverified assumptions.
+
+Use native source annotations only for changed locations when the host supports
+them. Otherwise use `path:line` in the console; never simulate annotations by
+editing source.