@homericintelligence/athena-opencode 0.4.4 → 0.5.1

package/skills/test-driven-development/SKILL.md

@@ -1,74 +1,155 @@
 ---
 name: test-driven-development
 license: BSD-3-Clause
-description: Use when implementing any feature or bugfix, before writing implementation code — enforces RED-GREEN-REFACTOR cycle
+description: Use this skill before you write implementation code for a feature or bug fix. Follow the RED-GREEN-REFACTOR cycle. Do not write production code until a verified test fails for the expected missing behavior. If the test has an error, correct the test before GREEN.
 argument-hint: <feature or bugfix description>
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
 ---
 
-# Test-Driven Development (TDD)
+# Test-driven development (TDD)
 
-Why: seeing a focused test fail proves it can detect the missing product
-behavior; seeing it pass proves the smallest implementation satisfies it.
+A focused test that fails proves that it can detect the missing product behavior. A passing test
+proves that the smallest implementation satisfies the test.
 
-Use Athena's shared [behavior-first testing guidance](../../docs/review/behavior-first-testing.md)
-for good-test/bad-test criteria, determinism, and false-pass checks. Test
-observable product behavior and core contracts, not wording, documentation
-layout, or a private implementation arrangement.
+Apply the [ASD-STE100 technical-English policy](../TECHNICAL_ENGLISH.md) to this skill and to
+all prose that it produces.
 
-## Use and rule
+Use Athena's shared [behavior-first testing guidance](../_support/docs/review/behavior-first-testing.md)
+for test criteria, determinism, and false-pass checks. Test observable product behavior and core
+contracts. Do not test wording, documentation layout, or a private implementation arrangement.
 
-Use TDD for features, bug fixes, refactoring, and behavior changes. Ask the
-human partner before exempting a throwaway prototype, generated code,
-configuration-only work, or documentation-only wording/layout change. In a
-swarm, the test specialist completes RED before implementation begins.
+## Engineering principles
+
+Use Athena's [canonical engineering-principles catalog](../_support/docs/principles/README.md) for the
+principle definitions. Use these principles in this workflow:
+
+- [P022 — Test Behavior, Not Implementation](../_support/docs/principles/README.md#p022): Write tests for
+  observable contracts. Do not write tests for a private implementation.
+- [P023 — Parameterized / Table-Driven Testing](../_support/docs/principles/README.md#p023): If one rule is
+  applicable to two or more test cases, use named data in a parameterized or table-driven test.
+- [P024 — Boundary-Value Testing](../_support/docs/principles/README.md#p024): If the behavior has
+  boundaries, include values near its limits and state changes.
+- [P025 — Property-Based Testing for Invariants](../_support/docs/principles/README.md#p025): If a small
+  example set is not sufficient for an invariant, use generated input families.
+- [P026 — Regression Before Repair](../_support/docs/principles/README.md#p026): If it is possible, before
+  you repair the defect, add one test that fails only because of the defect.
+- [P027 — Deterministic and Hermetic Tests](../_support/docs/principles/README.md#p027): Set environment
+  inputs to specified values. Control external boundaries. Make sure that each test gives the same
+  result each time.
+- [P028 — Test Failure Paths, Not Just Success Paths](../_support/docs/principles/README.md#p028): If the
+  contract includes failure paths, include invalid input, dependency failure, cancellation, and
+  cleanup.
+- [P091 — Test-Driven Development](../_support/docs/principles/README.md#p091): For a behavior change, first
+  add a test that shows the missing behavior (`RED`). Then, make the minimum code change that makes
+  the test pass (`GREEN`). After `GREEN`, make the structure better without a behavior change
+  (`REFACTOR`).
+
+## Working rules
+
+Use TDD for features, bug fixes, and behavior changes. For a pure refactor that preserves behavior,
+first establish a verified green characterization baseline. Then, start at REFACTOR. Do not create
+an artificial RED result.
+
+If the work introduces or changes observable behavior, start with RED. Before you exempt a
+throwaway prototype, generated code, configuration-only work, or documentation-only change, ask the
+human partner. In a swarm, the test specialist must complete the applicable RED or green
+characterization baseline before implementation starts.
 
 ```text
-NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+START A BEHAVIOR CHANGE WITH A FOCUSED FAILING TEST
+START A PURE REFACTOR FROM A VERIFIED GREEN BASELINE
 ```
 
-If you wrote in-scope implementation first, remove only that newly authored
-work and start with RED. Preserve pre-existing or user-authored work and ask for
-direction when provenance or scope is unclear.
-
-## RED–GREEN–REFACTOR
-
-1. **RED:** Write one minimal, clearly named test for one observable behavior,
-   data contract, security property, or executable artifact outcome. Use real
-   code unless a controlled substitute is needed at a genuine external boundary.
-2. **Verify RED:** Discover the repository's focused test command and run it.
-   The test must fail—not error—for the expected missing behavior. A filtered
-   command must prove it selected a relevant test; C++/CMake tests must be wired
-   to a real build and test target. If the test passes, it covers existing
-   behavior; if it errors, fix the test setup and run it again.
-3. **GREEN:** Write the simplest behaviorally complete code that passes. Do not
-   add speculative features, unrelated refactors, or implementation beyond the
-   test's demonstrated need.
-4. **Verify GREEN:** Run the discovered relevant suite. The new and existing
-   tests must pass without errors or warnings; fix code rather than weakening a
-   test.
-5. **REFACTOR:** After green, remove duplication, clarify names, or extract a
-   helper without adding behavior. Keep tests green, then start the next RED
-   cycle.
-
-For documentation-only changes, use existing Markdown, link, and executable
-example validation. Do not create production code or a text-assertion harness
-to manufacture a RED phase.
+If you wrote an in-scope implementation that changes behavior before RED, remove only the work that
+you added. Then, start with RED. If a pure refactor started without a verified baseline, stop.
+Establish a verified baseline before you continue. Preserve existing work and work that the user
+authored. If the source or scope of the work is not clear, ask for direction.
+
+## RED-GREEN-REFACTOR
+
+For a refactor that preserves behavior, verify the existing characterization suite. Then, start at
+step 5. If the intended work changes the observable contract, return to RED.
+
+1. **RED:** Write one minimum, clearly named test under
+   [P022](../_support/docs/principles/README.md#p022).
+
+   - The test must cover one observable behavior, data contract, security property, or executable
+     artifact result.
+   - Use real code unless a real external boundary requires a controlled substitute.
+   - If the behavior requires them, apply [P023](../_support/docs/principles/README.md#p023),
+     [P024](../_support/docs/principles/README.md#p024),
+     [P025](../_support/docs/principles/README.md#p025), and
+     [P028](../_support/docs/principles/README.md#p028).
+
+2. **Verify RED:** Verify the RED result with the focused test command for the repository.
+
+   - Before you run the command, find it in the repository.
+   - Run the focused test command.
+   - The test must fail for the expected missing behavior.
+   - The test must not stop because of a test error.
+   - For a filtered command, use the output to prove that the command selected an applicable test.
+   - Connect each C++/CMake test source to a real build target and test target.
+   - If the test passes, it covers existing behavior.
+   - If the test has an error, correct the test setup. Then, run the test again.
+   - Under [P027](../_support/docs/principles/README.md#p027), keep the test deterministic and isolated.
+
+3. **GREEN:** Write the simplest behaviorally complete code that passes the behavior test.
+
+   - Follow [P001 — KISS — Keep It Simple, Stupid](../_support/docs/principles/README.md#p001).
+   - Prefer [P090 — Prefer Negative Code](../_support/docs/principles/README.md#p090) only if the candidate
+     solutions are equally correct.
+   - Do not add speculative features, unrelated refactors, or implementation beyond the need that
+     the test shows.
+
+4. **Verify GREEN:** Run the applicable test suite that you found in the repository.
+
+   - The new and existing tests must pass without errors or warnings.
+   - Correct the code. Do not weaken a test.
+
+5. **REFACTOR:** After GREEN, improve the structure without new behavior.
+
+   - Remove actual knowledge duplication under
+     [P003 — DRY — Don't Repeat Yourself](../_support/docs/principles/README.md#p003).
+   - Do not violate [P013 — AHA — Avoid Hasty Abstractions](../_support/docs/principles/README.md#p013).
+   - Protect [P070 — Code Health Must Not Regress](../_support/docs/principles/README.md#p070),
+     [P084 — Prefer Local Reasoning](../_support/docs/principles/README.md#p084), and
+     [P086 — Readability Counts](../_support/docs/principles/README.md#p086).
+   - Prefer deletion under [P090](../_support/docs/principles/README.md#p090) only if behavior and clarity
+     do not change.
+   - Keep the tests green.
+   - Start the next RED cycle.
+
+For a documentation-only change, use existing Markdown, link, and executable-example validation.
+Do not create production code. Do not create a text-assertion harness to produce an artificial RED
+phase.
 
 ## Evidence before completion
 
-Discover commands from `AGENTS.md`, task runners, manifests, lockfiles, and
-required CI; prefer repository-native entry points. Record focused and relevant
-suite, coverage, type, and lint commands when applicable. If they conflict or
-no safe command is discoverable, ask the user rather than borrow another
-repository's command.
-
-Before completion, confirm proportionate coverage for every changed observable
-behavior and bug regression; controlled time, services, randomness, state, and
-mocks where the product requires them; non-empty focused test selection; and
-fresh passing relevant tests, type checks, and lint. Follow the evidence policy
-before claiming success. Use `learn` for a durable testing lesson; its own
-scope and delivery rules determine whether it publishes a PR.
+Find commands in `AGENTS.md`, task runners, manifests, lockfiles, and required continuous
+integration (CI) configuration. Prefer repository-native entry points. When applicable, record the
+focused-test, applicable-suite, coverage, type-check, and lint commands. If the sources conflict or
+you cannot find a safe command, ask the user. Do not use a command from another repository.
+
+Before completion, confirm these conditions:
+
+- Each changed observable behavior and bug regression has proportionate test coverage.
+- The tests control time, services, randomness, state, and mocks when the product requires this
+  control.
+- Focused test selection is not empty.
+- Fresh applicable tests, type checks, and lint checks pass.
+
+Before you claim success, follow the
+[evidence-integrity policy](../_support/docs/policies/evidence-integrity.md). For a durable testing lesson,
+use `learn`. The scope and delivery rules of `learn` determine if it publishes a pull request.
+
+## Failed approaches
+
+- Do not write production code before RED.
+- Do not keep in-scope implementation that you wrote before the test.
+- Do not accept a test error as RED. Correct the setup. Then, run the test until it fails for the
+  expected missing behavior.
+- Do not weaken a test to reach GREEN. Correct the code.
+- Do not add speculative features or unrelated refactors beyond the need that the test shows.
 
 ---
 

package/skills/tidy/SKILL.md

@@ -1,68 +1,132 @@
 ---
 name: tidy
 license: BSD-3-Clause
-description: Delegate repository branch and worktree cleanup to the dependency-locked Hephaestus tidy command. Use for tidy, cleanup, or rebase requests; fail closed when the trusted automation checkout or required execution capability cannot be prepared.
+description: Delegate repository branch and worktree cleanup to the dependency-locked Hephaestus tidy command. Use this skill for a tidy, cleanup, or rebase request. Stop if the trusted automation checkout or a required execution capability cannot be prepared.
 argument-hint: "<optional: hephaestus-tidy arguments>"
 allowed-tools: [Bash, Read]
 ---
 
 # Tidy through Hephaestus
 
-Use this when the user asks to tidy, clean up, or rebase a repository's local branches or
-worktrees. Athena prepares the trusted automation dependency and delegates the complete operation;
-`hephaestus-tidy` owns discovery, preservation rules, prompts, rebases, removal safeguards, output,
-and the final exit status.
+Use this skill when the user asks to tidy, clean up, or rebase local repository branches or
+worktrees. Athena prepares the trusted automation dependency. Then, Athena delegates the complete
+operation to `hephaestus-tidy`.
+
+`hephaestus-tidy` controls:
+
+- discovery;
+- preservation rules;
+- prompts;
+- rebases;
+- removal safeguards;
+- output;
+- final exit status.
+
+Apply the [ASD-STE100 technical-English policy](../TECHNICAL_ENGLISH.md) to this skill and to
+all prose that it produces.
+
+## Engineering principles
+
+Use the [canonical engineering-principles catalog](../_support/docs/principles/README.md) for these
+workflow rules:
+
+- [P010 — Scope Fidelity](../_support/docs/principles/README.md#p010): Delegate only the requested tidy,
+  cleanup, or rebase operation. Do not add a different cleanup policy for Athena.
+- [P031 — Propagate Rather Than Swallow](../_support/docs/principles/README.md#p031): Give the delegated
+  command's output, signals, and nonzero result to the caller. Do not hide the failure. Do not
+  automatically retry it.
+- [P035 — Fail Secure / Fail Closed](../_support/docs/principles/README.md#p035): If a dependency identity or
+  revision-binding check is not satisfactory, stop. If the checkout is not clean, stop. If a
+  necessary capability is not available, stop.
+- [P050 — Least Privilege](../_support/docs/principles/README.md#p050): Use only the resolved dependency,
+  target repository, capabilities, and arguments that are necessary for this invocation.
+- [P058 — Bounded Agent Authority](../_support/docs/principles/README.md#p058): When you forward arguments,
+  do not increase the user's scope, destinations, credentials, or mutation authority.
+- [P061 — Separate Decision from High-Impact Execution](../_support/docs/principles/README.md#p061): Before
+  you start delegated execution, record the dependency, target, authority, and full command vector.
+  Validate the record. During execution, use only the recorded values.
+- [P062 — Human Approval for Irreversible or High-Risk Actions](../_support/docs/principles/README.md#p062):
+  If the user gave authority for scoped constructive work, do not request a second approval. If the
+  user did not give authority for a destructive or irreversible action, request approval for that
+  specified action.
+- [P083 — Irreversible Actions Last](../_support/docs/principles/README.md#p083): Before you start an
+  irreversible operation, complete the dependency and command validation.
 
 ## Inputs
 
-Keep the target repository as the current working directory. Treat every argument supplied to this
-skill as a `hephaestus-tidy` argument and forward it unchanged. When the user wants a preview,
-forward `--dry-run`; do not reinterpret it or add it implicitly.
+Keep the target repository as the current working directory. Treat each user argument as a
+`hephaestus-tidy` argument. Forward it without a change. If the user wants a preview, forward
+`--dry-run`. Do not reinterpret this option. Do not add it implicitly.
+
+Under [P053 — Validate at Trust Boundaries](../_support/docs/principles/README.md#p053), treat the arguments
+as opaque, untrusted command-line data. Preserve the boundary of each argument. The
+`hephaestus-tidy` parser is the nearest responsible validation boundary.
 
 ## Workflow
 
 1. Prepare Hephaestus at `$HOME/.agent_brain/automation` under the canonical
-   [`dependency-resolution` contract](../../docs/dependency-resolution.md). Report the resolved
-   repository, commit SHA, and trust basis. Resolution, authentication, checkout, update,
-   cleanliness, identity, revision-binding, or automatic-fork revalidation failure is blocking.
-2. Keep the target repository as the current working directory. Resolve `scripts/run_tidy.py`
-   against this installed skill directory and invoke that absolute helper path with the resolved
-   automation checkout as its first internal operand, followed by every user argument in its
-   original order and form.
-3. The helper replaces itself with this dependency-locked command vector:
+   [`dependency-resolution` contract](../_support/docs/dependency-resolution.md).
+2. Report the resolved repository, commit SHA, and trust basis.
+3. If resolution, authentication, checkout, update, cleanliness, identity, revision binding, or
+   automatic-fork revalidation fails, stop.
+4. Keep the target repository as the current working directory.
+5. Resolve `scripts/run_tidy.py` against this installed skill directory.
+6. Invoke the absolute helper path with this operand order:
+
+   - the resolved automation checkout as the first internal operand;
+   - each user argument after the first operand, in its original order and form.
+7. The helper replaces itself with this dependency-locked command vector:
 
    ```text
    uv run --project <resolved-automation-checkout> --locked hephaestus-tidy <user-arguments>
    ```
 
-4. Leave stdin, stdout, and stderr attached. Do not capture, pipe, summarize in place of, answer,
-   retry, or otherwise mediate the command. The user answers any interactive prompt emitted by
-   Hephaestus.
+8. Leave stdin, stdout, and stderr attached.
+9. Do not capture the command.
+10. Do not pipe the command.
+11. Do not replace the command output with a summary.
+12. Do not answer an interactive prompt from Hephaestus. The user answers each prompt.
+13. Do not retry the command.
+14. Do not otherwise mediate it.
+
+Athena does not do these operations:
+
+- worktree audit;
+- candidate classification;
+- removal;
+- prompt;
+- branch rebase;
+- cleanup safety decision.
+
+Do not replace the dependency-locked command with a `hephaestus-tidy` executable from `PATH`.
 
-Athena performs no worktree audit, candidate classification, removal, prompt, branch rebase, or
-cleanup safety decision of its own. It never substitutes a `hephaestus-tidy` executable found on
-`PATH` for the dependency-locked command.
+Delegation keeps existing authority for constructive actions that are in scope. It does not create
+new authority. Keep the Hephaestus prompts attached. Do not use delegation to bypass action-bound
+approval. This restriction applies to each destructive or other irreversible operation that the user
+did not authorize.
 
 ## Dependency and capability failures
 
-Authenticated `gh`, Git, and network access are required by dependency preparation. Python 3 and
-`uv` are required to start the locked command. On any missing capability or nonzero command result,
-return the failure unchanged and stop. Do not fall back to a stale checkout, a similarly named
-repository, an ambient executable, or a second cleanup implementation.
+Dependency preparation requires authenticated `gh`, Git, and network access. The locked command
+requires Python 3 and `uv`. If a capability is not available or the command result is nonzero,
+return the failure without a change. In that case, stop. Do not use a stale checkout, a repository with a
+similar name, an ambient executable, or a second cleanup implementation.
 
 ## Failed approaches
 
-- Auditing and removing worktrees in Athena duplicated Hephaestus policy and produced a second set
-  of destructive-action prompts.
-- Invoking an ambient `hephaestus-tidy` could bypass the resolved repository and its lockfile.
-- Parsing, normalizing, or reconstructing user arguments changed the delegated CLI contract.
-- Capturing or piping the process could alter interactive behavior, output, signals, or exit status.
+- Do not audit worktrees in Athena. Do not remove worktrees in Athena. These actions duplicate the
+  Hephaestus policy and create a second set of destructive-action prompts.
+- Do not invoke an ambient `hephaestus-tidy`. It can bypass the resolved repository and its lockfile.
+- Do not parse user arguments. Do not normalize user arguments. Do not reconstruct user arguments.
+  These actions change the delegated command-line contract.
+- Do not capture the process. Do not pipe the process. These actions can change interactive behavior,
+  output, signals, or exit status.
 
 ## Output
 
 Before execution, report the resolved Hephaestus repository, commit SHA, and trust basis. After
-that, preserve the delegated command's output and terminal result without adding Athena-specific
-worktree classifications or cleanup conclusions.
+execution starts, preserve the delegated command output and terminal result. Do not add
+Athena-specific worktree classifications or cleanup conclusions.
 
 ## Attribution
 

package/skills/tidy/scripts/run_tidy.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Replace this process with the dependency-locked Hephaestus tidy command."""
+"""Run the dependency-locked Hephaestus tidy command in place of this process."""
 
 from __future__ import annotations
 
@@ -34,9 +34,9 @@ def main(argv: Sequence[str] | None = None) -> int:
         os.execvp(command[0], command)
     except FileNotFoundError as error:
         missing = error.filename or command[0]
-        print(f"required command unavailable: {missing}", file=sys.stderr)
+        print(f"The required command is not available: '{missing}'.", file=sys.stderr)
         return 127
-    raise RuntimeError("os.execvp returned unexpectedly")
+    raise RuntimeError("The os.execvp call returned control unexpectedly.")
 
 
 if __name__ == "__main__":