@homericintelligence/athena-opencode 0.5.0 → 0.5.2

package/skills/_support/docs/principles/details/p017-high-cohesion-low-coupling.md

@@ -0,0 +1,130 @@
+# P017 — High Cohesion, Low Coupling
+
+## Definition
+
+Put related responsibilities and related state in one component. Use the smallest number of weak
+dependencies necessary for system operation.
+
+Cohesion measures internal relation. Coupling measures component dependence.
+
+**Aliases:** strong cohesion and loose coupling, functional cohesion and weak coupling.
+
+## Provenance
+
+**Classification:** established principle.
+
+Stevens, Myers, and Constantine gave definitions for coupling and cohesion in structured design
+during the 1970s. Practitioners then gave the short maxim. No one source contains the maxim.
+
+## Decision rule
+
+Put elements that change for the same reason in one component. Use the smallest stable contract
+that preserves necessary behavior to connect components.
+
+## How to apply
+
+- Use change history and domain ownership to find cohesive boundaries.
+- Keep each invariant with its related state.
+- Pass only data or capability that is necessary for a collaborator. Do not share mutable global data.
+- Examine cross-module change patterns, dependency cycles, and wide interfaces.
+- Coupling metrics give evidence only. Make sure that each result agrees with domain knowledge.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    Change["Requested change"] --> Compare{"Same reason to change?"}
+    Compare -->|Yes| Cohesive["Keep responsibilities together"]
+    Compare -->|No| Split["Put in different components"]
+    Cohesive --> Contract["Give consumers a narrow contract"]
+    Split --> Contract
+    Contract --> Consumer["Use only necessary consumer dependencies"]
+```
+
+## Language examples
+
+The two examples keep price rules cohesive. Checkout depends only on a narrow quote contract.
+
+Python:
+
+```python
+class U32(int):
+    def __new__(cls, value: int):
+        if type(value) is not int or not 0 <= value <= 0xFFFF_FFFF:
+            raise ValueError("value must be u32")
+        return int.__new__(cls, value)
+class Quoter:
+    def quote(self, subtotal: U32) -> U32: raise NotImplementedError
+class Pricing(Quoter):
+    def quote(self, subtotal: U32) -> U32:
+        return U32(subtotal - (10 if subtotal >= 100 else 0))
+def checkout_total(quoter: Quoter, subtotal: U32) -> U32:
+    return quoter.quote(subtotal)
+```
+
+Rust:
+
+```rust
+trait Quoter {
+    fn quote(&self, subtotal: u32) -> u32;
+}
+struct Pricing;
+impl Quoter for Pricing {
+    fn quote(&self, subtotal: u32) -> u32 {
+        subtotal - if subtotal >= 100 { 10 } else { 0 }
+    }
+}
+fn checkout_total(quoter: &impl Quoter, subtotal: u32) -> u32 {
+    quoter.quote(subtotal)
+}
+```
+
+## Boundaries and tensions
+
+Each system has some coupling. Event buses, generic data maps, and duplicate state can
+hide coupling.
+
+A definition that puts too many responsibilities together can make a large component. Use explicit
+dependencies, not implicit coordination. Select a design that gives component independence and transaction consistency.
+
+## Examples
+
+### Positive application
+
+A pricing component owns discount rules and their necessary inputs. Checkout uses only a narrow
+quote contract. Checkout does not use pricing tables or cache details.
+
+### Misuse or counterexample
+
+Two services send many events to each other and share a database. These services do not make synchronous
+calls. This fact does not make the services loosely coupled.
+
+### Athena or agent workflow
+
+A skill-local helper does one parsing task and gives a stable CLI. The skill uses only that
+CLI. Other skills do not import private helper code.
+
+## Related principles
+
+- [P016 — Separation of Concerns](p016-separation-of-concerns.md)
+- [P018 — Information Hiding](p018-information-hiding.md)
+- [P019 — Explicit Contracts](p019-explicit-contracts.md)
+
+## References
+
+### Source information
+
+- [Stevens, Myers, and Constantine, "Structured Design" (1974)](https://doi.org/10.1147/sj.132.0115)
+  gives module coupling and cohesion categories.
+
+### Applicable information
+
+- [Microsoft Azure Architecture Center, "Design for evolution"](https://learn.microsoft.com/en-us/azure/architecture/guide/design-principles/design-for-evolution)
+  shows how cohesion and loose coupling let one service change without changes to other services.
+
+### More information
+
+- [SEI, "Modifiability Tactics" (2007)](https://www.sei.cmu.edu/documents/778/2007_005_001_14858.pdf)
+  gives an analysis of responsibility, coupling, cohesion, and change propagation.
+
+[Back to the engineering principles catalog](../README.md#p017)

package/skills/_support/docs/principles/details/p018-information-hiding.md

@@ -0,0 +1,128 @@
+# P018 — Information Hiding
+
+## Definition
+
+Give consumers a stable contract and hide implementation decisions that can change.
+Consumers use only the component guarantees. They do not use the component representation, algorithm,
+dependency, or operational details.
+
+**Aliases:** encapsulation of design decisions, implementation hiding.
+
+## Provenance
+
+**Classification:** established principle.
+
+David Parnas used information hiding as a module decomposition criterion in 1972. Encapsulation
+is a related principle. Language-level access control does not hide each implementation
+decision that can change.
+
+## Decision rule
+
+Give consumers only the facts that they must use. Keep each implementation decision that can change
+behind the boundary.
+
+## How to apply
+
+- Find possible change points, for example storage formats, vendors, algorithms, and cache
+  policy.
+- Publish operations and semantic guarantees. Do not publish internal fields or dependency objects.
+- Do not use shared tables or mutable aliases to give access to private representations.
+- Before you change an implementation, do tests of the public contract.
+- Record each specified escape path and its compatibility cost.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Consumer["Consumer"] --> Contract["Stable contract"]
+    Contract --> Component["Component"]
+    Component --> Choice["Hidden implementation decision"]
+    Choice --> Replace["Replace implementation"]
+    Replace --> Contract
+```
+
+## Language examples
+
+The two examples give store operations to consumers and hide the map representation.
+
+Python:
+
+```python
+class TokenStore:
+    def __init__(self) -> None:
+        self._tokens: dict[str, str] = {}
+
+    def save(self, user: str, token: str) -> None:
+        self._tokens[user] = token
+
+    def load(self, user: str) -> str | None:
+        return self._tokens.get(user)
+```
+
+Rust:
+
+```rust
+use std::collections::HashMap;
+
+pub struct TokenStore { tokens: HashMap<String, String> }
+impl TokenStore {
+    pub fn new() -> Self { Self { tokens: HashMap::new() } }
+    pub fn save(&mut self, user: String, token: String) {
+        self.tokens.insert(user, token);
+    }
+    pub fn load(&self, user: &str) -> Option<&str> {
+        self.tokens.get(user).map(String::as_str)
+    }
+}
+```
+
+## Boundaries and tensions
+
+Information hiding must show behavior that is necessary for correct operation. This behavior includes
+side effects, ownership, latency, failure modes, and consistency guarantees.
+
+Without evidence for more than one possible implementation, do not make an abstraction.
+Observability can show safe diagnostic facts. It must not show mutable internals or sensitive
+data.
+
+## Examples
+
+### Positive application
+
+A repository publishes `save` and `load` operations. The repository owns its schema and migration
+details. Callers do not write SQL or use table names.
+
+### Misuse or counterexample
+
+A wrapper makes its fields private and returns its mutable collection. Consumers can use that
+representation and corrupt it.
+
+### Athena or agent workflow
+
+A skill invokes a specified helper command and interprets its exit contract. It does not import
+private helper modules or use log text that is not part of the exit contract.
+
+## Related principles
+
+- [P016 — Separation of Concerns](p016-separation-of-concerns.md)
+- [P017 — High Cohesion, Low Coupling](p017-high-cohesion-low-coupling.md)
+- [P019 — Explicit Contracts](p019-explicit-contracts.md)
+
+## References
+
+### Source information
+
+- [Parnas, "On the Criteria To Be Used in Decomposing Systems into Modules" (1972)](https://doi.org/10.1145/361598.361623)
+  recommends modules that hide design decisions, not process-step modules.
+
+### Applicable information
+
+- [Oracle, "Strong Encapsulation in the JDK"](https://docs.oracle.com/en/java/javase/25/migrate/migrating-jdk-8-later-jdk-releases.html)
+  gives a platform boundary that hides unsupported internals from consumers.
+
+### More information
+
+- [SEI, "Software Architecture"](https://www.sei.cmu.edu/software-architecture/)
+  gives explicit structural decisions and conformance during system evolution.
+
+[Back to the engineering principles catalog](../README.md#p018)

package/skills/_support/docs/principles/details/p019-explicit-contracts.md

@@ -0,0 +1,134 @@
+# P019 — Explicit Contracts
+
+## Definition
+
+When ambiguity can cause defects, give boundary obligations and guarantees. A contract
+includes all properties that are necessary for correct operation.
+
+These properties can include inputs, outputs, preconditions, postconditions, invariants, units,
+ownership, mutability, side effects, concurrency, and failures.
+
+**Aliases:** interface contract, behavioral contract.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+Bertrand Meyer's Design by Contract gives a related formal foundation. It is not a full
+alias. Meyer made preconditions, postconditions, and invariants part of the method.
+
+This principle also includes operational and ownership properties.
+
+## Decision rule
+
+Two parties can make different assumptions about a boundary. Before operation, encode or record each
+material assumption.
+
+## How to apply
+
+- Give accepted and rejected inputs. Give units, ranges, nullability, and encoding.
+- Give observable outputs, side effects, order, consistency, and error categories.
+- When applicable, put contracts in types, schemas, assertions, tests, or protocol definitions.
+- Give the owner and lifetime of mutable data and resources.
+- Version external contracts. Each semantic change is a compatibility decision.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Boundary["System boundary"] --> Ambiguity{"Are assumptions different?"}
+    Ambiguity -->|No| Minimal["Keep the smallest necessary contract"]
+    Ambiguity -->|Yes| Define["Give obligations and guarantees"]
+    Define --> Encode["Encode or record"]
+    Encode --> Verify["Verify observable behavior"]
+```
+
+## Language examples
+
+The two examples accept signed-64 integer inputs and return typed errors for values not in that
+range.
+
+Python:
+
+```python
+I64_MIN, I64_MAX = -(1 << 63), (1 << 63) - 1
+class OutOfRangeError(ValueError): ...
+class NegativeRequestError(ValueError): ...
+class InsufficientCapacityError(ValueError): ...
+
+def reserve_bytes(requested: int, capacity: int) -> int:
+    if type(requested) is not int or type(capacity) is not int or not (I64_MIN <= requested <= I64_MAX and I64_MIN <= capacity <= I64_MAX):
+        raise OutOfRangeError("signed-64 range required")
+    if requested < 0:
+        raise NegativeRequestError("negative request")
+    if requested > capacity:
+        raise InsufficientCapacityError("insufficient capacity")
+    return capacity - requested
+```
+
+Rust:
+
+```rust
+enum ReserveError { OutOfRange, NegativeRequest, InsufficientCapacity }
+
+fn reserve_bytes(requested: i128, capacity: i128) -> Result<i64, ReserveError> {
+    let range = i64::MIN as i128..=i64::MAX as i128;
+    if !range.contains(&requested) || !range.contains(&capacity) { return Err(ReserveError::OutOfRange); }
+    if requested < 0 { return Err(ReserveError::NegativeRequest); }
+    if requested > capacity { return Err(ReserveError::InsufficientCapacity); }
+    Ok((capacity - requested) as i64)
+}
+```
+
+## Boundaries and tensions
+
+Full prose is not necessary for each internal helper. Contract detail changes with ambiguity, risk,
+and consumer count.
+
+A schema cannot contain all semantic promises. Generated documentation does not replace executable
+verification. Do not show implementation details that can change in contract coverage reports.
+
+## Examples
+
+### Positive application
+
+A batch API uses bytes for sizes. It rejects negative values and preserves input order. It
+returns a typed partial-failure result and preserves caller-owned data.
+
+### Misuse or counterexample
+
+An endpoint publishes a JSON shape. The endpoint does not give retry behavior. Callers do not know if a retry
+can duplicate a write.
+
+### Athena or agent workflow
+
+A skill gives necessary inputs, permitted capabilities, success evidence, and safe failure output.
+A host can invoke the skill without guesses about hidden preconditions.
+
+## Related principles
+
+- [P018 — Information Hiding](p018-information-hiding.md)
+- [P020 — Executable Architecture](p020-executable-architecture.md)
+- [P029 — Generalize Error Policy; Preserve Specific Cause](p029-generalize-error-policy-preserve-specific-cause.md)
+
+## References
+
+### Source information
+
+- [Meyer, "Applying Design by Contract" (1992)](https://doi.org/10.1109/2.161279)
+  shows how explicit client and supplier obligations can increase software reliability.
+
+### Applicable information
+
+- [JSON Schema specification, Draft 2020-12](https://json-schema.org/specification)
+  gives a machine-readable vocabulary for JSON structure and validation.
+- [OpenAPI Specification v3.2.0](https://spec.openapis.org/oas/v3.2.0.html)
+  gives versioned contracts for HTTP operations, parameters, request bodies, responses, and
+  schemas.
+
+### More information
+
+- [RFC 9457, "Problem Details for HTTP APIs" (2023)](https://www.rfc-editor.org/rfc/rfc9457.html)
+  shows a stable error contract with general problem types and event-specific detail.
+
+[Back to the engineering principles catalog](../README.md#p019)

package/skills/_support/docs/principles/details/p020-executable-architecture.md

@@ -0,0 +1,130 @@
+# P020 — Executable Architecture
+
+## Definition
+
+Encode important architectural constraints in mechanisms that verify implementation conformance.
+Possible mechanisms include tests, type systems, schemas, static analysis, dependency rules, CI
+policy, and runtime guards.
+
+Documentation gives the explanation. Executable checks detect drift.
+
+**Aliases:** architecture fitness functions, architecture tests, automated architecture
+governance.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+No one source gives this architectural practice. Ford, Parsons, and Kua give architecture fitness
+functions. Tools before their work also enforced dependency and conformance rules.
+
+## Decision rule
+
+When a mechanically observable architecture violation can cause material risk, add the smallest
+accurate check. Put the check at the nearest feedback boundary.
+
+## How to apply
+
+- Select a small number of important qualities or dependency rules.
+- Select the lowest-cost mechanism that verifies the rule, for example a compiler, linter, test, or
+  CI check.
+- Make failure output identify the violated rule and the related dependency or artifact.
+- Add the rule and its check in the same change.
+- After an approved architecture change, revise the check. Revise the rule and implementation in
+  the same change.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Rule["Architecture rule"] --> Observable{"Mechanically observable?"}
+    Observable -->|No| Review["Use design review"]
+    Observable -->|Yes| Check["Add the smallest accurate check"]
+    Check --> Change["Verify each change"]
+    Change --> Drift{"Rule violation?"}
+    Drift -->|Yes| Reject["Report edge that violates rule"]
+    Drift -->|No| Accept["Accept conformance"]
+```
+
+## Language examples
+
+The two examples make the same dependency direction an executable rule.
+
+Python:
+
+```python
+ALLOWED = {("api", "domain"), ("storage", "domain")}
+
+def dependency_allowed(source: str, target: str) -> bool:
+    return (source, target) in ALLOWED
+
+def test_domain_cannot_depend_on_api() -> None:
+    assert not dependency_allowed("domain", "api")
+```
+
+Rust:
+
+```rust
+const ALLOWED: [(&str, &str); 2] = [("api", "domain"), ("storage", "domain")];
+
+fn dependency_allowed(source: &str, target: &str) -> bool {
+    ALLOWED.contains(&(source, target))
+}
+
+#[test]
+fn domain_cannot_depend_on_api() {
+    assert!(!dependency_allowed("domain", "api"));
+}
+```
+
+## Boundaries and tensions
+
+Some architectural properties are not computable. A proxy metric can give a pass result to incorrect
+behavior or reject correct designs. Human review must examine semantics and trade-offs.
+
+Do not use prose-string tests, snapshot inventories, or dependency rules about file layout. Such
+checks prevent layout changes that do not change architecture. They do not verify a consumer-related boundary.
+
+## Examples
+
+### Positive application
+
+A dependency test rejects imports from the domain layer into transport adapters. The test gives the
+edge that violates the rule. The architecture document gives the explanation for the direction.
+
+### Misuse or counterexample
+
+A test fails when a document does not have a specified heading. The test gives incorrect evidence of
+modularity enforcement. The test prevents word changes but does not verify architectural behavior.
+
+### Athena or agent workflow
+
+Athena's validator finds canonical skill entry points and rejects host-specific skill mirrors. The
+repository policy gives the boundary. The validator prevents distribution drift.
+
+## Related principles
+
+- [P019 — Explicit Contracts](p019-explicit-contracts.md)
+- [P021 — Evolutionary and Reversible Design](p021-evolutionary-and-reversible-design.md)
+- [P027 — Deterministic and Hermetic Tests](p027-deterministic-and-hermetic-tests.md)
+
+## References
+
+### Source information
+
+- [Ford, Parsons, and Kua, *Building Evolutionary Architectures*, second-edition sample](https://www.thoughtworks.com/content/dam/thoughtworks/documents/books/bk_building_evolutionary_architectures_second_edition_free_chapter.pdf)
+  gives information about fitness functions as objective checks for architectural change.
+
+### Applicable information
+
+- [ArchUnit User Guide](https://www.archunit.org/userguide/html/000_Index.html)
+  gives executable dependency, layer, cycle, and custom architecture rules for Java systems.
+- [SEI, "Software Architecture"](https://www.sei.cmu.edu/software-architecture/)
+  gives conformance analysis and fitness evaluation after architecture changes.
+
+### More information
+
+- [Thoughtworks, *Building Evolutionary Architectures* sample chapter](https://www.thoughtworks.com/content/dam/thoughtworks/documents/books/bk_building_evolutionary_architectures_en.pdf)
+  gives automated and manual fitness functions and their trade-offs.
+
+[Back to the engineering principles catalog](../README.md#p020)

package/skills/_support/docs/principles/details/p021-evolutionary-and-reversible-design.md

@@ -0,0 +1,126 @@
+# P021 — Evolutionary and Reversible Design
+
+## Definition
+
+Use incremental, behavior-preserving, and migration-safe steps to change a system. Keep a tested
+method to use the previous state again or continue to a safe state.
+
+During a transition, compatible versions can operate together. Use evidence from small
+changes, not evidence from one large rewrite.
+
+**Aliases:** evolutionary design, incremental architecture, reversible change.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+Sources for this synthesis include evolutionary design, continuous delivery, expand-and-contract
+migrations, and restoration practices. No one source gives the full principle.
+
+## Decision rule
+
+Select the smallest sequence of verifiable changes. Each change must preserve service. Until
+verification of the new state succeeds, keep a tested recovery path.
+
+## How to apply
+
+- Divide work at compatibility boundaries. Keep each merged state operational.
+- When risks are different, use different steps for preparation, activation, migration, and cleanup.
+- When evidence shows a compatibility risk, use additive schema changes, dual reads, dual writes,
+  feature controls, or adapters.
+- Before activation of a risky change, give restoration or forward recovery.
+- After evidence shows that there are no consumers, remove transition mechanisms.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    Prepare["Prepare compatible state"] --> Deploy["Deploy compatible code"]
+    Deploy --> Migrate["Migrate with checkpoints"]
+    Migrate --> Verify{"New state verified?"}
+    Verify -->|No| Restore["Use previous state or continue safely"]
+    Verify -->|Yes| Activate["Activate new path"]
+    Activate --> Cleanup["Remove previous path"]
+```
+
+## Language examples
+
+The two examples accept previous and new names during one compatible migration period.
+
+Python:
+
+```python
+def read_name(old_name: str, new_name: str | None) -> str:
+    return new_name if new_name is not None else old_name
+
+
+def write_names(value: str) -> tuple[str, str]:
+    return value, value
+```
+
+Rust:
+
+```rust
+fn read_name<'a>(old_name: &'a str, new_name: Option<&'a str>) -> &'a str {
+    new_name.unwrap_or(old_name)
+}
+
+fn write_names(value: String) -> (String, String) {
+    (value.clone(), value)
+}
+```
+
+## Boundaries and tensions
+
+Reversibility has costs and limits. A legal notice, secret disclosure, resource consumption, or destructive
+migration can prevent reversal. Find each irreversible point and put it near the end of the
+sequence.
+
+Do not keep compatibility without a specified end or dual-write complexity for a small local change.
+If the previous version is safe and has a low restoration cost, use that version again.
+
+## Examples
+
+### Positive application
+
+A schema change first adds a nullable column. Compatible readers and writers accept each version. A
+checkpoint process migrates the data.
+
+The team selects the new column only after validation. The team removes the previous column in the
+last step.
+
+### Misuse or counterexample
+
+A team says that a flag-protected rewrite is reversible. But activation converts all stored data to a
+format that the previous release cannot read.
+
+### Athena or agent workflow
+
+An agent makes one small change and runs the repository gate. After verification of the artifact and
+its targets succeeds, the agent publishes only with applicable authority. Without user approval, it
+does not do destructive cleanup. After user approval, it uses the guarded tidy workflow.
+
+## Related principles
+
+- [P020 — Executable Architecture](p020-executable-architecture.md)
+- [P026 — Regression Before Repair](p026-regression-before-repair.md)
+- [P027 — Deterministic and Hermetic Tests](p027-deterministic-and-hermetic-tests.md)
+
+## References
+
+### Source information
+
+- [Fowler, "Original Strangler Fig Application" (2004)](https://martinfowler.com/bliki/OriginalStranglerFigApplication.html)
+  gives replacement in steps for a legacy system, without one cutover rewrite.
+
+### Applicable information
+
+- [Google Engineering Practices, "Small CLs"](https://google.github.io/eng-practices/review/developer/small-cls.html)
+  gives an explanation of how small changes simplify work.
+
+### More information
+
+- [Ford, Parsons, and Kua, *Building Evolutionary Architectures*, second-edition sample](https://www.thoughtworks.com/content/dam/thoughtworks/documents/books/bk_building_evolutionary_architectures_second_edition_free_chapter.pdf)
+  gives evolutionary architecture as guided, incremental change in more than one dimension.
+
+[Back to the engineering principles catalog](../README.md#p021)