@homericintelligence/athena-opencode 0.5.0 → 0.5.2

package/README.md

@@ -1,13 +1,20 @@
 # 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.
+[Athena](https://github.com/HomericIntelligence/Athena) packages its workflow skills as an
+[opencode](https://opencode.ai) plugin. The plugin contains the full canonical skill corpus. It puts
+the corpus in the opencode configuration directory. Opencode finds and loads the corpus there.
+
+Athena uses the
+[ASD-STE100 technical-English policy](skills/TECHNICAL_ENGLISH.md)
+for its English technical prose.
 
 ## Install
 
-Add the package to the `plugin` array of your opencode configuration
-(`~/.config/opencode/opencode.json` or a project `opencode.json`):
+Add the package to the `plugin` array in the opencode configuration. Use one of these configuration
+files:
+
+- `~/.config/opencode/opencode.json`; or
+- a project `opencode.json`.
 
 ```json
 {
@@ -16,29 +23,35 @@ Add the package to the `plugin` array of your opencode configuration
 }
 ```
 
-Quit and restart opencode. On startup the plugin copies the bundled `skills/` corpus to:
+Quit opencode. Then, restart opencode. During startup, the plugin copies the bundled `skills/` corpus
+to this location:
 
 ```
 $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.
+If `XDG_CONFIG_HOME` does not have a value, the target is
+`~/.config/opencode/skills/athena/`. The plugin writes only in the `athena/` namespace. It does not
+change other skills in your configuration. At each restart, the plugin makes the namespace agree
+with the installed plugin version. Thus, a package update also updates 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.
+Use the native opencode skill mechanism. For example, ask opencode to use the `repo-review`,
+`pr-review`, or `plan-issue` skill. See the root
+[`README.md`](https://github.com/HomericIntelligence/Athena#readme) for this information:
+
+- the full skill catalog;
+- dependency requirements for Git and Python 3.13;
+- the authenticated GitHub CLI (`gh`) requirement 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.
+1. Remove `"@homericintelligence/athena-opencode"` from the `plugin` array.
+2. Restart opencode.
+3. To remove the files immediately, delete `opencode/skills/athena/` from your configuration
+   directory.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@homericintelligence/athena-opencode",
-  "version": "0.5.0",
-  "description": "Athena workflow skills packaged as an opencode plugin.",
+  "version": "0.5.2",
+  "description": "Athena provides workflow skills as an opencode plugin.",
   "license": "BSD-3-Clause",
   "type": "module",
   "main": "plugin.js",

package/plugin.js

@@ -1,4 +1,11 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  statSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -26,7 +33,7 @@ export function syncSkills() {
   const target = installTarget();
   if (!existsSync(join(source, "_cli.py"))) {
     throw new Error(
-      `Athena skill corpus is missing next to plugin.js: ${source}`,
+      `The plugin cannot find the Athena skills next to plugin.js: '${source}'.`,
     );
   }
   mkdirSync(dirname(target), { recursive: true });
@@ -39,7 +46,9 @@ async function athenaPlugin() {
   try {
     syncSkills();
   } catch (error) {
-    console.warn(`[athena-opencode] skill installation failed: ${error}`);
+    console.warn(
+      `[athena-opencode] The plugin could not install the skills: ${error}`,
+    );
   }
   return {};
 }
@@ -47,8 +56,14 @@ async function athenaPlugin() {
 export default athenaPlugin;
 
 export function bundledSkillNames() {
-  return readdirSync(bundledSkillsRoot(), { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
+  const root = bundledSkillsRoot();
+  return readdirSync(root, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() &&
+        existsSync(join(root, entry.name, "SKILL.md")) &&
+        statSync(join(root, entry.name, "SKILL.md")).isFile(),
+    )
     .map((entry) => entry.name)
     .sort();
 }

package/skills/TECHNICAL_ENGLISH.md

@@ -0,0 +1,78 @@
+# ASD-STE100 technical-English policy
+
+All Athena English technical prose must follow
+[ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/). This requirement applies to
+skills, agent directions, public documents, user messages that a skill produces, and text in a user
+interface.
+
+The literal text that this policy identifies does not have to obey it.
+
+## Authority
+
+Use the current official issue of ASD-STE100 as the authority. Request a copy from the
+[official download page](https://www.asd-ste100.org/STE_downloads.html).
+
+This repository policy does not copy or replace the standard. It does not replace approved
+training. Repository checks can find Markdown errors, broken package contracts, and some style
+risks. The checks do not certify conformance to ASD-STE100.
+
+## Required method
+
+Use these steps when you write or change technical prose:
+
+1. Read the applicable technical source before you write.
+2. Use approved words with their approved meanings and parts of speech.
+3. Use a technical noun or a technical verb when the approved dictionary has no necessary term.
+4. Use one term for one meaning.
+5. Do not use a different synonym for the same item or action.
+6. Use American English spelling unless an exact external name uses a different spelling.
+7. Use active voice when you know the actor.
+8. Use the imperative form for a direct instruction.
+9. Put a condition before the related action when the reader must know the condition first.
+10. Give one primary instruction in each numbered step.
+11. Keep sentences short.
+12. Split a sentence when it contains more than one independent idea.
+13. Use a vertical list when it makes complex information easier to identify.
+14. Avoid an `-ing` form when an approved, unambiguous form gives the same meaning.
+15. Define each abbreviation at its first use unless the intended readers always know it.
+16. Keep the technical meaning.
+17. Do not remove a necessary safety, evidence, permission, or failure condition to make a sentence
+    shorter.
+18. Review the result against the current official standard.
+
+## Literal text
+
+Do not change literal text only to make it conform to this policy. Literal text includes:
+
+- programming-language syntax and generated code;
+- commands, options, identifiers, paths, URLs, and API field names;
+- machine-readable markers, schemas, and data values;
+- legal text, licenses, and required notices;
+- attributed quotations; and
+- historical records that must preserve their original text.
+
+A message for a user or an agent is technical prose even when source code contains it. This rule
+applies to command help, error messages, status messages, prompts, and user-interface labels.
+
+Write the prose around literal text in accordance with ASD-STE100.
+
+Use code formatting or a quotation format to make the literal boundary clear.
+
+## Conflict and verification
+
+Technical accuracy, safety controls, security controls, evidence rules, and higher-authority
+instructions take precedence. If simplified wording changes the required meaning, use these steps:
+
+1. Keep the required meaning.
+2. Rewrite the sentence.
+
+Ask for a technical review when you cannot remove the ambiguity.
+
+If you cannot use the current official standard:
+
+- Apply this policy.
+- Report the verification gap.
+
+Do not state that the text conforms to ASD-STE100.
+
+Do not state that a person or tool certified or verified ASD-STE100 conformance.

package/skills/_cli.py

@@ -1,4 +1,4 @@
-"""Shared argparse construction for Athena's executable helpers."""
+"""This module provides shared command-line support for Athena helpers."""
 
 from __future__ import annotations
 
@@ -16,26 +16,29 @@ 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."""
+    """Run an external command and report a missing required capability."""
     if not arguments:
-        raise RuntimeError("required command is empty")
+        raise RuntimeError("The 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
+        raise RuntimeError(
+            f"The required command is not available: '{command}'."
+        ) from error
 
 
 def git_read_environment() -> dict[str, str]:
-    """Return a hermetic environment for immutable, non-interactive Git reads."""
+    """Return an isolated 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.
+    # to read an empty graft source. First, remove each inherited `GIT_*`
+    # setting. These settings can redirect or change an immutable read. They
+    # include location, object, index, configuration, attribute, pathspec, and
+    # transport settings.
     environment.update(
         {
             "GIT_ATTR_NOSYSTEM": "1",
@@ -58,7 +61,7 @@ def git_read_arguments() -> tuple[str, ...]:
 
 
 def require_complete_git_history(*, cwd: Path | None = None) -> None:
-    """Reject shallow history before deriving immutable ancestry evidence."""
+    """Reject shallow history before calculation of immutable ancestry evidence."""
     result = run_command(
         ["git", *git_read_arguments(), "rev-parse", "--is-shallow-repository"],
         capture_output=True,
@@ -69,20 +72,21 @@ def require_complete_git_history(*, cwd: Path | None = None) -> None:
     )
     if result.returncode != 0:
         message = (
-            result.stderr.strip() or "git rev-parse --is-shallow-repository failed"
+            result.stderr.strip()
+            or "The git rev-parse --is-shallow-repository command failed."
         )
         raise RuntimeError(message)
     if result.stdout.strip() != "false":
         raise RuntimeError(
-            "immutable review evidence requires a non-shallow repository; "
-            "use a complete source snapshot"
+            "The immutable review evidence needs 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."""
+    """Return the only immutable merge base or reject an ambiguous history."""
     result = run_command(
         [
             "git",
@@ -99,23 +103,28 @@ def require_unambiguous_git_merge_base(
         check=False,
     )
     if result.returncode != 0:
-        message = result.stderr.strip() or "git merge-base failed"
+        message = result.stderr.strip() or "The git merge-base command 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"
+            "The 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"
+    """Return this corpus's generated version or its adjacent canonical manifest."""
+    corpus = Path(__file__).resolve().parent
+    manifest = corpus / "_plugin.json"
+    if not manifest.exists() and corpus.name == "skills":
+        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}")
+    if not isinstance(version, str) or not version.strip():
+        raise TypeError(
+            f"The plugin manifest does not contain a string version: '{manifest}'."
+        )
     return version
 
 
@@ -132,9 +141,11 @@ class _PluginVersionAction(argparse.Action):
         del namespace, values, option_string
         try:
             version = plugin_version()
-        except (OSError, TypeError, json.JSONDecodeError) as error:
+        except (OSError, TypeError, UnicodeError, json.JSONDecodeError) as error:
             parser.exit(
-                1, f"{parser.prog}: error: cannot read plugin version: {error}\n"
+                1,
+                f"{parser.prog}: error: The tool cannot read the plugin version: "
+                f"{error}\n",
             )
         print(f"{parser.prog} {version}")
         parser.exit(0)
@@ -147,6 +158,6 @@ def argument_parser(*, description: str | None = None) -> argparse.ArgumentParse
         "--version",
         action=_PluginVersionAction,
         nargs=0,
-        help="show the Athena plugin version and exit",
+        help="Show the Athena plugin version and exit.",
     )
     return parser

package/skills/_plugin.json

@@ -0,0 +1 @@
+{"version": "0.5.2"}

package/skills/_support/docs/dependency-resolution.md

@@ -0,0 +1,203 @@
+# Repository resolution
+
+Apply the [ASD-STE100 technical-English policy](../../TECHNICAL_ENGLISH.md) to all English technical prose
+in this document.
+
+**Why:** Athena must use trusted and current repositories when it changes Mnemosyne or executes
+Hephaestus. Read-only knowledge can use a validated local checkout and then try a best-effort
+refresh. Athena must not report an unverified remote or stale checkout as current.
+
+## At a glance
+
+During normal resolution for a write or automation execution, Athena does these steps:
+
+1. It resolves a trusted owner.
+2. It synchronizes an exact checkout.
+3. It binds use to the reported revision.
+
+A trust, authentication, checkout, or update failure stops that write or automation execution.
+
+All read-only Mnemosyne paths validate the local checkout first. If `gh`, authentication, and
+network access are available, Athena then tries a best-effort refresh. If the refresh cannot run
+or fails, Athena keeps the validated local checkout and reports the freshness limit. This path
+must do these actions:
+
+- bind use to the current `HEAD`;
+- report the current `HEAD` or the refreshed revision;
+- report the freshness and trust limits;
+- never substitute a different repository; and
+- never make a durable write from that checked state.
+
+If local knowledge is unavailable, stop only knowledge retrieval. Continue the primary task. The
+`learn` skill can classify a candidate, but it must complete normal resolution and duplicate checks
+before a durable write.
+
+```mermaid
+flowchart LR
+    A["Resolve dependency"] --> B{"Read-only Mnemosyne use?"}
+    B -->|yes| C{"Is a local checkout readable?"}
+    C -->|no| E["Report no local guidance; continue primary task"]
+    C -->|yes| D["Bind local HEAD and report limits"]
+    D --> F{"Can gh auth and discovery run?"}
+    F -->|yes| G["Try refresh, then report the updated revision or the local fallback"]
+    F -->|no| H["Keep the validated local revision and report the freshness limit"]
+    B -->|no| I{"Is there an explicit owner?"}
+    I -->|yes| J["Validate override"]
+    I -->|no| K{"Is there a trusted organization fork?"}
+    K -->|yes| L["Use maintained fork"]
+    K -->|no| M["Use canonical upstream"]
+    J --> N["Verify origin and clean checkout"]
+    L --> N
+    M --> N
+    N --> O["Fetch, fast-forward, and bind SHA"]
+    O --> P["Revalidate automatic-fork trust before use"]
+```
+
+## Component details
+
+### Owner selection
+
+For a route that needs normal resolution of dependency `<Repository>` with environment override
+`<OWNER_VARIABLE>`, use these steps:
+
+1. If `<OWNER_VARIABLE>` is not empty, select `<value>/<Repository>`.
+
+   - Before you use the owner in a path or command, validate it as a GitHub owner name.
+   - If the explicit override is not valid, report an error.
+   - If the explicit override is not valid, stop.
+   - If the explicit override is not valid, do not use a fallback.
+   - The owner name must meet these requirements:
+
+     - It contains 1 through 39 characters.
+     - It contains only ASCII letters, digits, or single hyphens.
+     - It does not start or end with a hyphen.
+
+2. If `<OWNER_VARIABLE>` is empty, get the current repository owner with this command:
+
+   ```bash
+   gh repo view --json owner --jq .owner.login
+   ```
+
+   Use `<current-owner>/<Repository>` only when all these automatic-fork trust gates pass:
+
+   - The `owner.type` of the current repository is `Organization` and not `User`.
+   - The `viewerPermission` of the authenticated viewer on the current repository is `WRITE` (push),
+     `MAINTAIN`, or `ADMIN`.
+   - GitHub confirms that the candidate is a fork. Its `parent.full_name` must be
+     `HomericIntelligence/<Repository>`.
+   - Athena can resolve and report the candidate repository and the tip SHA of its remote default
+     branch.
+
+3. If no trusted override or automatic fork applies, use `HomericIntelligence/<Repository>`.
+
+Do not automatically select a repository with the same name in these conditions:
+
+- The owner of the current repository is a user.
+- The viewer has read, triage, or no permission.
+- Athena cannot prove canonical ancestry.
+
+Use repository metadata to make the fork decision. Do not use only the repository name:
+
+```bash
+current_owner=$(gh repo view --json owner --jq '.owner.login')
+gh api "repos/${current_owner}/<Repository>" \
+  --jq '.fork == true and .parent.full_name == "HomericIntelligence/<Repository>"'
+```
+
+Only the literal result `true` passes the ancestry check. Use structured application programming
+interface (API) output. Quote each derived value. Resolve these values:
+
+- the `owner.type` of the current repository;
+- the `viewerPermission` of the authenticated viewer;
+- the `.default_branch` of the candidate; and
+- the exact tip `.sha` of that branch.
+
+The fork can contain modified content after all automatic trust gates pass. If the same-owner
+candidate is missing or not eligible, use the canonical upstream repository. If an API or
+authentication error prevents a trustworthy decision, treat the error as fatal and stop.
+
+An explicit owner override is an explicit trust decision. It can select custom fork content without
+the organization and viewer-permission gate. Before you use a resolved dependency, report this
+information:
+
+- the exact repository;
+- the commit SHA; and
+- the trust basis: `explicit override`, `maintained organization fork`, or `canonical upstream`.
+
+### Dependency map
+
+| Purpose | Repository | Override | Checkout |
+| --- | --- | --- | --- |
+| Knowledge | `Mnemosyne` | `HOMERIC_INTELLIGENCE_MNEMOSYNE_OWNER` | `$HOME/.agent_brain/knowledge` |
+| Automation | `Hephaestus` | `HOMERIC_INTELLIGENCE_HEPHAESTUS_OWNER` | `$HOME/.agent_brain/automation` |
+
+### Checkout and revalidation
+
+Normal resolution applies to Mnemosyne delivery and Hephaestus execution. It requires these
+capabilities:
+
+- authenticated GitHub CLI (`gh`);
+- `git`; and
+- network access.
+
+Create `$HOME/.agent_brain` when it is necessary. If the checkout is absent, clone the resolved
+repository. For an existing checkout, do these checks and actions:
+
+- Require `origin` to identify the resolved `owner/repository`.
+- Do not overwrite local changes or silently change the remote.
+- Fetch `origin`.
+- Resolve the default branch of `origin`.
+- Fast-forward that branch.
+- Report the resolved repository and commit SHA.
+
+For an automatically selected same-owner fork, repeat the trust checks immediately before use. Do
+this before you write knowledge or execute automation. Re-query these values:
+
+- the Organization owner of the current repository;
+- the permission of the viewer;
+- the `parent.full_name` of the candidate;
+- the resolved repository identity;
+- the default branch; and
+- the tip SHA.
+
+Require these values to agree with the reported trust decision. Require the checked-out commit to
+agree with the re-queried tip SHA. Stop if a value does not agree. This check closes the race between
+resolution and use.
+
+### Read-only knowledge access
+
+Use this path for all read-only Mnemosyne retrieval. Inspect the existing checkout first. Bind use
+to the current `HEAD`. If `gh`, authentication, and network access are available, try a refresh. If
+the refresh cannot run or fails, keep the validated local checkout and report the freshness limit.
+
+Do not require the local checkout to have the newest Mnemosyne revision. Do not require its
+revision to agree with the installed Athena revision. The installed skill supplies its own
+retrieval contract.
+
+Report this information:
+
+- the checkout;
+- the revision;
+- the trust basis or trust uncertainty; and
+- the freshness limit.
+
+If the checkout is missing or inspection fails, stop the dependent knowledge retrieval. Continue the
+primary task. `learn` can classify an undelivered candidate, but it cannot make a duplicate decision
+or publish a write until normal resolution succeeds.
+
+For Hephaestus execution and the `learn` delivery boundary, these conditions are fatal:
+
+- an authentication failure;
+- a missing repository;
+- a fork relationship that is not valid;
+- an unexpected `origin`;
+- conflicting local state;
+- a clone failure;
+- a fetch failure; or
+- a fast-forward failure.
+
+Read-only local access never permits pull-request creation before upstream synchronization.
+
+Mnemosyne writes use isolated worktrees and always end in a pull request. Athena reads or executes
+Hephaestus from its canonical checkout. Athena never edits Hephaestus unless the user explicitly asks
+for a Hephaestus change.