@homericintelligence/athena-opencode 0.4.4 → 0.5.1

package/skills/git-worktrees/scripts/prepare_worktree.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Select, validate, and optionally create an isolated Git worktree."""
+"""Prepare an isolated Git worktree."""
 
 from __future__ import annotations
 
@@ -22,23 +22,27 @@ def git(
         ["git", *arguments], cwd=cwd, capture_output=True, text=True, check=False
     )
     if check and result.returncode != 0:
-        raise RuntimeError(result.stderr.strip() or f"git {' '.join(arguments)} failed")
+        raise RuntimeError(
+            result.stderr.strip() or f"The git {' '.join(arguments)} command failed."
+        )
     return result
 
 
 def reject_symlinks_below(trust_root: Path, target: Path) -> None:
-    """Reject symlinks in the caller-controlled path below a trusted root."""
+    """Reject symbolic links in a caller-controlled path below a trusted root."""
     lexical_root = trust_root.absolute()
     lexical_target = target.absolute()
     try:
         lexical_target.relative_to(lexical_root)
     except ValueError as error:
         raise RuntimeError(
-            f"worktree path escapes trusted root {lexical_root}"
+            f"The worktree path is outside the trusted root: '{lexical_root}'."
         ) from error
     for component in (*reversed(lexical_target.parents), lexical_target):
         if component.is_symlink():
-            raise RuntimeError(f"worktree path component is a symlink: {component}")
+            raise RuntimeError(
+                f"A component of the worktree path is a symbolic link: '{component}'."
+            )
 
 
 def select_path(
@@ -66,7 +70,8 @@ def select_path(
         if directory.is_dir():
             if directory.is_symlink():
                 raise RuntimeError(
-                    f"project-local worktree directory is a symlink: {directory}"
+                    "The project-local worktree directory is a symbolic link: "
+                    f"'{directory}'."
                 )
             return (directory / branch).resolve(), True
     project = root.name
@@ -82,7 +87,8 @@ def verify_ignored(root: Path, path: Path) -> None:
     result = git(root, "check-ignore", "-q", "--", str(probe), check=False)
     if result.returncode != 0:
         raise RuntimeError(
-            f"project-local worktree directory {relative.parent} is not ignored"
+            "Git did not confirm that it ignores the project-local worktree directory: "
+            f"'{relative.parent}'."
         )
 
 
@@ -102,9 +108,9 @@ def main() -> int:
             root, "check-ref-format", "--branch", arguments.branch, check=False
         )
         if branch_check.returncode != 0:
-            raise RuntimeError(f"invalid branch name: {arguments.branch}")
+            raise RuntimeError(f"The branch name is not valid: '{arguments.branch}'.")
         if (arguments.path is None) != (arguments.path_root is None):
-            raise RuntimeError("--path and --path-root must be provided together")
+            raise RuntimeError("Specify '--path' and '--path-root' together.")
         path, project_local = select_path(
             root,
             arguments.branch,
@@ -121,7 +127,7 @@ def main() -> int:
         if project_local:
             verify_ignored(root, path)
         if path.exists():
-            raise RuntimeError(f"worktree path already exists: {path}")
+            raise RuntimeError(f"The worktree path already exists: '{path}'.")
         if not arguments.dry_run:
             git(
                 root,

package/skills/issue-review/SKILL.md

@@ -1,67 +1,163 @@
 ---
 name: issue-review
 license: BSD-3-Clause
-description: Review a GitHub or GitLab issue and its current plan-issue artifact for architecture alignment, scope, risks, and behavior-first verification. Use before implementation; `--report-only` is read-only.
+description: Use before implementation to review a GitHub or GitLab issue and its current `plan-issue` artifact. Check architecture, scope, risk, and behavior-first verification. Use `--report-only` for read-only work.
 argument-hint: "[--report-only] ISSUE_NUMBER_OR_URL"
 allowed-tools: [Read, Bash, Grep, Glob, Agent, WebFetch]
 ---
 
 # Review an issue and plan
 
-Why: find architecture, scope, and verification gaps while changing the plan is
-still cheaper than changing code.
+Purpose: Review the plan before implementation. Early review helps you find architecture, scope,
+and verification gaps before code changes start.
 
-Use the shared [issue-planning contract](../../docs/review/issue-planning.md),
-[review contract](../../docs/review/common.md),
-[language routing](../../docs/review/language-routing.md), and
-[behavior-first testing](../../docs/review/behavior-first-testing.md).
+Apply the [ASD-STE100 technical-English policy](../TECHNICAL_ENGLISH.md) to this skill and to all
+prose that it produces.
+
+Use the shared [issue-planning contract](../_support/docs/review/issue-planning.md),
+[review contract](../_support/docs/review/common.md),
+[language routing](../_support/docs/review/language-routing.md), and
+[behavior-first testing](../_support/docs/review/behavior-first-testing.md).
+
+## Engineering principles
+
+Use the canonical [engineering-principles catalog](../_support/docs/principles/README.md) for these review
+decisions:
+
+- [P010 Scope Fidelity](../_support/docs/principles/README.md#p010): Use the current issue and canonical
+  plan as the full review target.
+- [P066 Preserve Existing Work](../_support/docs/principles/README.md#p066): Do not rewrite historical
+  artifacts or artifacts that a different actor owns.
+- [P012 Evidence Before Modification](../_support/docs/principles/README.md#p012): Before you accept a
+  plan, examine current requirements and repository evidence.
+- [P063 Requirement-to-Code Traceability](../_support/docs/principles/README.md#p063): For each gap,
+  find the related requirement or contract.
+- [P072 Technical Evidence Over Preference](../_support/docs/principles/README.md#p072): Give technical
+  evidence for each gap. Do not use personal preference as evidence.
+- [P015 Architecture Conformance](../_support/docs/principles/README.md#p015): If a boundary violation has
+  no explanation, do not accept the plan.
+- [P071 Consistency Over Personal Preference](../_support/docs/principles/README.md#p071): If technical
+  evidence does not show a necessary change, obey repository conventions.
+- [P008 Understand Before Subtracting](../_support/docs/principles/README.md#p008): Before you accept
+  deletion or consolidation, examine the consumers and purpose.
 
 ## Scope and delivery
 
-The issue is the requirements source; review only its current canonical plan.
-Resolve plan ownership, marker, absence, and identity under the issue-planning
-contract. Historical plans and reviews are bounded context, not the artifact
-under review.
+Use the issue as the requirements source. Review only its current canonical plan. Use the
+issue-planning contract to identify the plan owner, marker, presence or absence, and identity. Use
+historical plans and reviews only as background information.
+
+If the request includes `--report-only`, this skill is read-only. Do not publish a comment. If the
+request does not include this option, first compare the required identities. Then, confirm a safe
+forge capability. You can then publish exactly one actor-owned structured review comment. Do not
+expand the scope to these items:
 
-`--report-only` is read-only. A requested review without it may publish exactly
-one actor-owned structured review comment after the required identity comparison
-and forge-capability check. It does not expand scope to labels, assignment,
-implementation, commit, push, pull request, merge, or issue closure.
+- labels;
+- assignment;
+- implementation;
+- commit;
+- push;
+- pull request;
+- merge; or
+- issue closure.
 
 ## Review
 
-1. Read the issue, linked work, canonical plan, repository guidance, ADRs,
-   relevant code, tests, and public contracts.
-2. Decide architecture first: aligned, intentional and justified change, or an
-   unexplained violation. A material violation blocks a positive assessment.
-3. Map every acceptance criterion to a concrete plan step, affected boundary,
-   and behavior-first validation step. For a material architecture change,
-   verify that the plan includes or cites a
-   [design record](../../docs/review/design-docs.md).
-4. Verify cited paths, symbols, commands, dependencies, assumptions, risks,
-   migration, and rollback claims against current repository evidence.
-5. Apply only activated language and change-surface checks, recording N/A
-   sections and reasons. Confirm that relevant prior findings are resolved,
-   rather than merely acknowledged.
-
-Prioritize architecture violations, missing requirements, unsafe scope,
-unresolved dependencies, untestable outcomes, invalid references,
-non-deterministic tests, empty selections, and unsupported claims.
-
-When reviewing after a finalized epoch, do not reinterpret generated plan text
-or sealed provenance as new requirements. Review only a later material issue
-change and its current canonical plan; an unchanged finalized epoch is not a
-new review target.
-
-Immediately before a requested publication, re-resolve the canonical planning
-identity. On drift, foreign or multiple markers, verified absence changes, or
-missing safe forge capability, withhold the comment and return the review as
-stale. Otherwise publish exactly one actor-owned structured comment, including
-a clean result or verified absent-plan coverage gap.
+1. Read the issue, linked work, canonical plan, repository guidance, architecture decision records
+   (ADRs), applicable code, tests, and public contracts.
+2. Under [P015 Architecture Conformance](../_support/docs/principles/README.md#p015), select one architecture
+   result:
+
+   - aligned;
+   - intentional and justified change; or
+   - unexplained violation.
+
+   A material violation prevents a positive assessment.
+3. Under [P063 Requirement-to-Code Traceability](../_support/docs/principles/README.md#p063), map each
+   acceptance criterion to a concrete plan step, affected boundary, and behavior-first validation
+   step.
+4. If the plan contains a material architecture change, verify that it includes or cites a
+   [design record](../_support/docs/review/design-docs.md).
+5. Under [P012 Evidence Before Modification](../_support/docs/principles/README.md#p012), verify these claims
+   against current repository evidence:
+
+   - paths;
+   - symbols;
+   - commands;
+   - dependencies;
+   - assumptions;
+   - risks;
+   - migration; and
+   - rollback.
+
+6. Apply only the language and change-surface checks that the review scope activates.
+7. Record each not applicable (`N/A`) section and its reason.
+8. Activate these principle checks only for their specified surfaces:
+
+   - Use [P001 KISS — Keep It Simple, Stupid](../_support/docs/principles/README.md#p001) for added
+     complexity.
+   - Use [P022 Test Behavior, Not Implementation](../_support/docs/principles/README.md#p022) for testable
+     behavior.
+   - Use
+     [P029 Generalize Error Policy; Preserve Specific Cause](../_support/docs/principles/README.md#p029) for
+     error paths.
+   - Use [P048 Secure by Design](../_support/docs/principles/README.md#p048) for security or new trust
+     boundaries.
+
+9. Confirm that each applicable prior finding is resolved. Acknowledgment alone does not resolve a
+   finding.
+
+Give priority to these findings:
+
+- architecture violations;
+- missing requirements;
+- unsafe scope;
+- unresolved dependencies;
+- outcomes that cannot be tested;
+- invalid references;
+- nondeterministic tests;
+- empty selections; and
+- unsupported claims.
+
+After a finalized epoch, do not treat generated plan text or sealed provenance as new requirements.
+Review only a later material issue change and its current canonical plan. An unchanged finalized
+epoch is not a new review target.
+
+Immediately before you publish the requested comment, resolve the canonical planning identity again.
+If one of these conditions is true, withhold the comment:
+
+- identity drift;
+- a foreign marker;
+- multiple markers;
+- a change to verified absence; or
+- no safe forge capability.
+
+If you withhold the comment, report the `stale` status.
+
+Otherwise, publish exactly one actor-owned structured comment. Include a clean result or verified
+absent-plan coverage gap.
+
+## Failed approaches
+
+- Do not review issues or plans outside the requested scope. Do not treat historical plans as the
+  artifact under review.
+- Do not edit the issue, labels, or assignment. If publication is authorized, report findings only in
+  the structured review comment. For `--report-only`, return the findings without publication.
+- Do not invent acceptance criteria that the reporter did not state. Do not accept an unresolved
+  prior finding only because someone acknowledged it.
+- After drift, do not publish the comment again. Withhold it. Report `stale`.
 
 ## Result
 
-Return issue and plan identities, architecture decision first, requirement
-mapping, severity-ranked findings, test-quality coverage, N/A sections,
-residual risks, and whether the comment was published or withheld. A review
-never expands scope to implementation or merge.
+Return these items:
+
+- issue and plan identities;
+- the architecture decision first;
+- the requirement map;
+- severity-ranked findings;
+- test-quality coverage;
+- `N/A` sections;
+- residual risks; and
+- whether you published or withheld the comment.
+
+Do not expand the review scope to implementation or merge.