@homericintelligence/athena-opencode 0.4.4 → 0.5.1

package/skills/_support/docs/principles/details/p070-code-health-must-not-regress.md

@@ -0,0 +1,116 @@
+# P070 — Code Health Must Not Regress
+
+## Definition
+
+A correct local result does not prove the quality of the full change. Without a necessary technical
+basis, a change must not decrease clarity, maintenance quality, test quality, operation
+quality, adaptability, or security. Use incremental improvement. Prevent code decay. Do not make
+perfection necessary.
+
+**Aliases:** leave the codebase no worse, continuous code-health improvement.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+This rule agrees with Google's published code-review standard. Many practitioners use related
+"leave it better" heuristics. No verified source has exclusive ownership of the full heuristic.
+
+## Decision rule
+
+When a change completes necessary work without a material loss of code health, accept it although
+it is not perfect. When a design has an unnecessary code-health cost that is more than its scoped
+benefit, revise it. If a revision cannot remove that cost, reject the design. Examine maintenance,
+complexity, test quality, operation, and security costs.
+
+## How to apply
+
+- Examine design, complexity, tests, naming, documentation, operation, and security in context.
+- Prevent a system-wide decrease in code health from a sequence of small local compromises.
+- Distinguish necessary corrections from optional style changes. Identify optional suggestions
+  clearly.
+- Use small, coherent changes that are easy to review, revert, and make better.
+- When you accept debt, document its necessity, owner, risk, and repair trigger.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Specify necessary change"] --> B["Select narrow design"]
+    B --> C["Examine system-wide code health"]
+    C --> D{"Material regression without a necessary basis?"}
+    D -- "Yes" --> E["Revise design or decrease scope"]
+    E --> C
+    D -- "No" --> F{"Temporary debt necessary?"}
+    F -- "Yes" --> G["Record owner, risk, and repair trigger"]
+    F -- "No" --> H["Accept change"]
+    G --> H
+```
+
+## Language examples
+
+The two examples add one clear data transformation with clear names and no new framework.
+
+```python
+def visible_tasks(tasks):
+    eligible = [task for task in tasks if task.active]
+    ordered = sorted(eligible, key=lambda task: task.priority)
+    return [task.title for task in ordered]
+```
+
+```rust
+fn visible_tasks(tasks: &[Task]) -> Vec<&str> {
+    let mut eligible: Vec<_> = tasks.iter().filter(|task| task.active).collect();
+    eligible.sort_by_key(|task| task.priority);
+    eligible.iter().map(|task| task.title.as_str()).collect()
+}
+```
+
+## Boundaries and tensions
+
+This principle does not authorize cleanup that is not part of the task or style changes that are not
+necessary. It does not make perfect code necessary before delivery.
+[P010 Scope Fidelity](p010-scope-fidelity.md) continues to limit the change. An emergency can make a
+recorded temporary compromise necessary. A local convention does not authorize extension of a known
+defect. Repository-wide repair can belong to a different task.
+
+## Examples
+
+**Positive:** A small feature uses the established interface and adds focused tests. It also makes
+one name in the changed area clearer without a large refactor.
+
+**Misuse:** A second copy duplicates security policy because a change to the canonical component has
+a larger scope.
+
+**Athena/agent workflow:** A reviewer separates a necessary contract-drift finding from an optional
+preference. This distinction protects the skill corpus without an expansion of task scope.
+
+## Related principles
+
+- [P010 Scope Fidelity](p010-scope-fidelity.md)
+- [P011 Minimal Coherent Change](p011-minimal-coherent-change.md)
+- [P065 Verify Before Claiming Completion](p065-verify-before-claiming-completion.md)
+- [P071 Consistency Over Personal Preference](p071-consistency-over-personal-preference.md)
+- [P072 Technical Evidence Over Preference](p072-technical-evidence-over-preference.md)
+
+## References
+
+### Source information
+
+- [Google Engineering Practices: The standard of code review](https://google.github.io/eng-practices/review/reviewer/standard.html)
+  is the primary practitioner source for code health as the primary review purpose. This page
+  does not identify all earlier sources.
+
+### Applicable information
+
+- [Google Engineering Practices: What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  applies code health to design, function, complexity, tests, names, comments, style, and
+  documentation.
+
+### More information
+
+- [Google Engineering Practices: Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)
+  shows that narrow changes increase review depth and design quality. Narrow changes also make
+  reversal and maintenance easier.
+
+[Back to the engineering principles catalog](../README.md#p070)

package/skills/_support/docs/principles/details/p071-consistency-over-personal-preference.md

@@ -0,0 +1,117 @@
+# P071 — Consistency Over Personal Preference
+
+## Definition
+
+When more than one correct alternative is available, obey established repository conventions,
+style guides, patterns, terms, and architecture. If a different correct style is only a personal
+preference, do not rewrite correct code.
+
+**Aliases:** local consistency, convention over personal preference.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+Language and project style guides use consistency rules. No verified source owns the practice. This
+rule uses consistency to select between equivalent alternatives. Consistency does not give authority
+to keep defects.
+
+## Decision rule
+
+When more than one method satisfies the same requirements, first compare the technical evidence.
+If the evidence shows no material difference, use the repository's established method. If
+evidence shows a material difference, apply
+[P072 Technical Evidence](p072-technical-evidence-over-preference.md).
+
+## How to apply
+
+- Read repository instructions, code in the same area, public contracts, and active architecture
+  decisions.
+- Use established terminology, layout, error conventions, test style, and extension mechanisms.
+- When the feature does not make modernization or formatting necessary, put that work in a
+  different change.
+- Propose clear convention changes. Apply accepted changes to all applicable code.
+- Record the technical basis for a convention exception.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Identify correct alternatives"] --> B{"Does evidence show that one alternative is better?"}
+    B -- "Yes" --> C["Select evidence-supported alternative"]
+    B -- "No" --> D["Examine repository convention"]
+    D --> E{"Convention is safe and current?"}
+    E -- "Yes" --> F["Use established convention"]
+    E -- "No" --> G["Propose clear convention change"]
+```
+
+## Language examples
+
+The two examples use the established `api_response` helper and its standard envelope.
+
+```python
+def create_user(request):
+    user = User.from_request(request)
+    payload = user.to_dict()
+    return api_response(payload, status=201)
+```
+
+```rust
+fn create_user(request: Request) -> Response {
+    let user = User::from_request(request);
+    let payload = user.to_map();
+    api_response(payload, Status::Created)
+}
+```
+
+## Boundaries and tensions
+
+Correctness, security, accessibility, specified requirements, and measured evidence have higher
+priority than consistency. When code in the same area contains a known vulnerability or invalid
+pattern, do not reproduce it. A repository can have an active transition between conventions.
+Then, obey the documented direction, not the style that occurs most frequently. Consistency protects
+reader expectations. It does not make the same appearance necessary at all costs.
+
+## Examples
+
+**Positive:** Two serialization approaches are equally correct. Thus, a new endpoint uses the
+repository serializer and error envelope.
+
+**Misuse:** A contributor rewrites a full module with a different name and format style in one
+small behavior change.
+
+**Athena/agent workflow:** A skill author obeys Athena's host-neutral terms and section
+conventions. The author does not introduce vendor-specific terms for the same capability.
+
+## Related principles
+
+- [P006 Principle of Least Astonishment](p006-principle-of-least-astonishment.md)
+- [P014 Preserve Unrequested Behavior](p014-preserve-unrequested-behavior.md)
+- [P015 Architecture Conformance](p015-architecture-conformance.md)
+- [P070 Code Health Must Not Regress](p070-code-health-must-not-regress.md)
+- [P072 Technical Evidence Over Preference](p072-technical-evidence-over-preference.md)
+
+## References
+
+### Source information
+
+- [PEP 8: A Foolish Consistency Is the Hobgoblin of Little Minds](https://peps.python.org/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds)
+  is a language guide with a long history. It gives priority to project consistency and gives rules
+  for exceptions with technical evidence. This page does not claim it as the initial source for the
+  full heuristic.
+
+### Applicable information
+
+- [Google Go Style Guide: Local consistency](https://google.github.io/styleguide/go/guide.html#local-consistency)
+  uses local convention to select between equal alternatives. It rejects consistency that extends a
+  defect or violates a stronger rule.
+- [Google Engineering Practices: The standard of code review](https://google.github.io/eng-practices/review/reviewer/standard.html)
+  gives style guides higher priority than personal preference. The guide gives technical facts
+  higher priority than style guides and personal preference.
+
+### More information
+
+- [Google JavaScript Style Guide: Reformatting existing code](https://google.github.io/styleguide/jsguide.html#policies-reformatting-existing-code)
+  shows the trade-off between consistency, code churn, and change focus.
+
+[Back to the engineering principles catalog](../README.md#p071)

package/skills/_support/docs/principles/details/p072-technical-evidence-over-preference.md

@@ -0,0 +1,122 @@
+# P072 — Technical Evidence Over Preference
+
+## Definition
+
+Use requirements, specifications, measurements, tests, profiles, architecture, and established
+engineering principles to resolve technical decisions. When applicable evidence shows that one
+alternative is better, do not use personal preference. Personal preference can select between
+alternatives that the evidence shows are equivalent for the decision.
+
+**Aliases:** facts over opinions, evidence-based engineering judgment.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+Evidence-based decisions have scientific and engineering roots in many fields. No verified software
+source owns the idea. Google's code-review guidance states the rule for review disputes. Athena
+applies the rule to plans, implementation, validation, and review.
+
+## Decision rule
+
+When approaches conflict, identify applicable evidence. Examine its quality. Select the alternative
+that agrees with trusted requirements and technical evidence. If there are equivalent
+alternatives, use established convention or the responsible author's preference.
+
+## How to apply
+
+- State the disputed claim and the observation that can distinguish the alternatives.
+- Compare evidence for relevance, trustworthiness, reproducibility, and applicability to the
+  workload.
+- Use accepted requirements and specifications, not reports without evidence or author preference.
+- When the environment changes behavior, use representative tests, benchmarks, and production data.
+- For use in a future decision, record important evidence and uncertainty.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["State disputed technical claim"] --> B["Identify necessary observation"]
+    B --> C["Collect trusted applicable evidence"]
+    C --> D{"Does evidence show that one alternative is better?"}
+    D -- "Yes" --> E["Select supported alternative"]
+    D -- "No" --> F{"Alternatives equivalent for decision?"}
+    F -- "Yes" --> G["Use convention or owner preference"]
+    F -- "No" --> H["Record uncertainty and collect more evidence"]
+```
+
+## Language examples
+
+The two examples select a parser from measurements of representative samples.
+
+```python
+def choose_parser(samples):
+    results = [
+        (measure(parser, samples), parser) for parser in PARSERS
+    ]
+    return min(results, key=lambda item: item[0])[1]
+```
+
+```rust
+fn choose_parser(samples: &[Input]) -> &'static Parser {
+    let measured: Vec<_> = PARSERS
+        .iter()
+        .map(|parser| (measure(parser, samples), parser))
+        .collect();
+    measured
+        .into_iter()
+        .min_by_key(|(cost, _)| *cost)
+        .expect("PARSERS is not empty").1
+}
+```
+
+## Boundaries and tensions
+
+Measurements and tests can be stale, biased, or applicable to an incorrect contract. Measurements
+can also have missing data. Examine evidence quality, not evidence quantity. Architecture and
+principles give a basis for judgment but do not override a specified higher-priority requirement.
+When stronger evidence does not show that one alternative is better, use
+[P071 Consistency](p071-consistency-over-personal-preference.md). If there is no data, risk is
+possible.
+
+## Examples
+
+**Positive:** Representative profiles identify serialization as the latency bottleneck. The team
+optimizes that path, not a low-cost component.
+
+**Misuse:** A reviewer blocks a correct, established implementation because a different syntax
+"feels cleaner." The reviewer gives no contract, measurement, or design effect.
+
+**Athena/agent workflow:** An agent finds a conflict between repository prose and executable
+behavior. Before the agent proposes a change, it examines history, validators, tests, and current
+policy.
+
+## Related principles
+
+- [P012 Evidence Before Modification](p012-evidence-before-modification.md)
+- [P063 Requirement-to-Code Traceability](p063-requirement-to-code-traceability.md)
+- [P065 Verify Before Claiming Completion](p065-verify-before-claiming-completion.md)
+- [P071 Consistency Over Personal Preference](p071-consistency-over-personal-preference.md)
+- [P073 Optimize Only With Evidence](p073-optimize-only-with-evidence.md)
+
+## References
+
+### Source information
+
+- [Google Engineering Practices: The standard of code review](https://google.github.io/eng-practices/review/reviewer/standard.html)
+  states that technical facts and data have higher priority than opinions and personal preferences.
+  This page does not claim it as the initial source.
+
+### Applicable information
+
+- [NASA SWE-194: Delivery Requirements Verification](https://swehb.nasa.gov/spaces/SWEHBVD/pages/102695529/SWE-194%2B-%2BDelivery%2BRequirements%2BVerification)
+  links acceptance evidence to requirements, test results, and recorded verification.
+- [NIST SSDF 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) gives risk-based secure-development
+  and verification practices with specified outcomes.
+
+### More information
+
+- [Athena evidence integrity policy](../../policies/evidence-integrity.md) specifies how repository
+  evidence claims must identify reproducible commands, revisions, environments, and recorded output.
+
+[Back to the engineering principles catalog](../README.md#p072)

package/skills/_support/docs/principles/details/p073-optimize-only-with-evidence.md

@@ -0,0 +1,123 @@
+# P073 — Optimize Only With Evidence
+
+## Definition
+
+If evidence does not identify an applicable constraint, do not add a cache, concurrency, batch
+process, or specialized data structure. Apply this rule to low-level tuning and architecture
+complexity. Measure a representative baseline. Find the bottleneck. Optimize that bottleneck. Then
+verify the improvement and correctness.
+
+**Aliases:** measurement before optimization, evidence-driven optimization.
+
+## Provenance
+
+**Classification:** established principle.
+
+Donald Knuth discussed premature optimization in 1974. No one author owns the general discipline or
+the Athena text. Performance tools and frameworks apply the rule with representative
+measurements.
+
+## Decision rule
+
+When an accepted requirement or trusted measurement shows an important constraint, add optimization
+complexity. Before-and-after evidence must show an improvement and must show that the result
+continues to satisfy the requirement.
+
+## How to apply
+
+- Specify the performance objective, workload, environment, and permitted trade-offs.
+- Record a reproducible baseline with representative data and end-to-end metrics.
+- Use a profile to find the dominant cost, not code appearance.
+- When possible, change one factor. Compare measurements from three or more runs.
+- Keep regression protection or monitoring for the optimized behavior.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Specify performance requirement"] --> B{"Constraint has evidence?"}
+    B -- "No" --> C["Keep simple design"]
+    B -- "Yes" --> D["Measure representative baseline"]
+    D --> E["Profile dominant cost"]
+    E --> F["Change one factor"]
+    F --> G{"Did the result stay correct and did the metric improve?"}
+    G -- "No" --> H["Reject or revise optimization"]
+    G -- "Yes" --> I["Keep regression evidence"]
+```
+
+## Language examples
+
+The two examples select the candidate only after proof of equal results and a lower measured cost.
+
+```python
+def select_parser(samples):
+    if outputs(parse, samples) != outputs(cached_parse, samples):
+        raise ValueError("candidate changes parser output")
+    baseline = measure(parse, samples)
+    candidate = measure(cached_parse, samples)
+    return cached_parse if candidate < baseline else parse
+```
+
+```rust
+fn select_parser(samples: &[Input]) -> Parser {
+    assert_eq!(outputs(parse, samples), outputs(cached_parse, samples));
+    let baseline = measure(parse, samples);
+    let candidate = measure(cached_parse, samples);
+    if candidate < baseline { cached_parse } else { parse }
+}
+```
+
+## Boundaries and tensions
+
+Specified latency, memory, cost, or capacity requirements can give evidence. A team can act before a
+production incident. Known algorithmic hazards and hard real-time constraints can make design work
+necessary before implementation. The team must specify the assumptions. The team must test them.
+
+When its workload differs from the target workload, a microbenchmark can give an incorrect result.
+If an optimization decreases correctness, security, clarity, or operation, a higher metric does not
+make the optimization correct.
+
+## Examples
+
+**Positive:** A representative profile shows that many parses dominate request latency. A bounded
+cache decreases that cost. Load tests verify latency, memory use, and correctness at the target
+scale.
+
+**Misuse:** A team adds concurrency, a cache, and a new service to a low-volume tool.
+No requirement, baseline, profile, or post-change measurement gives evidence for these additions.
+
+**Athena/agent workflow:** An agent proposes parallel subagents only for independent tasks with
+permitted coordination cost. Before a claim that maximum concurrency is faster, the agent uses
+evidence.
+
+## Related principles
+
+- [P001 KISS](p001-kiss.md)
+- [P002 YAGNI](p002-yagni.md)
+- [P012 Evidence Before Modification](p012-evidence-before-modification.md)
+- [P072 Technical Evidence Over Preference](p072-technical-evidence-over-preference.md)
+- [P080 Make Concurrency Deliberate](p080-make-concurrency-deliberate.md)
+
+## References
+
+### Source information
+
+- [Knuth, "Structured Programming with go to Statements" (1974)](https://doi.org/10.1145/356635.356640)
+  is a primary source for the important discussion of premature optimization and critical code
+  paths. It is not the only source for performance measurement.
+
+### Applicable information
+
+- [Go diagnostics documentation](https://go.dev/doc/diagnostics) gives profiling and tracing as tools
+  that find high-cost code and measure performance behavior.
+- [AWS Well-Architected Performance Efficiency Pillar](https://docs.aws.amazon.com/wellarchitected/latest/performance-efficiency-pillar/welcome.html)
+  states that teams must use performance indicators, monitoring, load tests, and regular
+  measurement-driven review.
+
+### More information
+
+- [Go profile-guided optimization](https://go.dev/doc/pgo) states that representative production
+  profiles give more applicable evidence. It also shows how narrow microbenchmarks can give
+  incorrect optimization input.
+
+[Back to the engineering principles catalog](../README.md#p073)

package/skills/_support/docs/principles/details/p074-prefer-existing-mechanisms.md

@@ -0,0 +1,121 @@
+# P074 — Prefer Existing Mechanisms
+
+## Definition
+
+Before you make a utility, abstraction, parser, serializer, retry framework, cache, or
+synchronization primitive, search for an applicable mechanism. Before you make a security
+mechanism, dependency, or service, search for an applicable mechanism. The repository, language,
+framework, platform, or standard library can supply it.
+
+**Aliases:** reuse before a new build, use established mechanisms first.
+
+## Provenance
+
+**Classification:** practitioner heuristic.
+
+Reuse of established components is a software practice with a long history. No verified source owns
+the practice. This rule gives priority to local and standard mechanisms. The rule continues to
+make a fitness and security assessment necessary because reuse does not always decrease risk.
+
+## Decision rule
+
+When the target environment supports an established mechanism and the mechanism satisfies the
+contract, use it. Its total correctness, security, maintenance, and operation cost must be lower
+than a new mechanism. As the default, make only the missing capability, not a second framework.
+
+## How to apply
+
+- Search repository code, documentation, dependency manifests, and architecture decisions first.
+- Then, examine the language and framework standard facilities.
+- Compare semantics, failure behavior, maintenance, provenance, licensing, and migration cost.
+- Add a small, coherent extension at the interface that the established mechanism supplies.
+- When available mechanisms do not satisfy the contract, document why a new mechanism is necessary.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Specify necessary capability"] --> B["Search repository mechanisms"]
+    B --> C["Search language and platform mechanisms"]
+    C --> D{"Does established mechanism satisfy contract?"}
+    D -- "Yes" --> E["Examine support, security, and total cost"]
+    E --> F{"Reuse has lower total risk?"}
+    F -- "Yes" --> G["Use or extend established mechanism"]
+    D -- "No" --> H["Make only missing capability"]
+    F -- "No" --> H
+```
+
+## Language examples
+
+The two examples use an established SHA-256 implementation. For the same input bytes, they return
+the same 32 digest bytes in the same order.
+
+```python
+from hashlib import sha256
+
+def digest(payload: bytes) -> bytes:
+    value = sha256(payload)
+    return value.digest()
+```
+
+```rust
+use sha2::{Digest, Sha256};
+
+fn digest(payload: &[u8]) -> Vec<u8> {
+    let value = Sha256::digest(payload);
+    value.to_vec()
+}
+```
+
+## Boundaries and tensions
+
+An established mechanism does not always satisfy the task contract or security requirements. Its
+owner can stop maintenance. If its contract does not include the work, do not use the mechanism. Do
+not use private internals. Do not keep a known vulnerability only to prevent new code. A third-party
+dependency can increase the supply-chain and attack surfaces.
+
+Thus, a small local implementation can be safer. Reuse must keep local analysis and clear
+ownership.
+
+## Examples
+
+**Positive:** A command uses the URL parser from the standard library and the repository error envelope. It
+does not make two replacements with small differences.
+
+**Misuse:** A custom retry loop duplicates the bounded retry in the repository client. The duplicate
+causes nested attempts and inconsistent delay intervals.
+
+**Athena/agent workflow:** An author invokes the documented CLI for a tested skill-local helper.
+The author does not add a second parser to a Markdown code block.
+
+## Related principles
+
+- [P003 DRY](p003-dry.md)
+- [P013 AHA](p013-avoid-hasty-abstractions.md)
+- [P057 Supply-Chain Integrity](p057-supply-chain-integrity.md)
+- [P078 Single Source of Truth](p078-single-source-of-truth.md)
+- [P084 Prefer Local Reasoning](p084-prefer-local-reasoning.md)
+
+## References
+
+### Source information
+
+- [Python tutorial: Batteries included](https://docs.python.org/3/tutorial/stdlib.html#batteries-included)
+  documents one important language philosophy for standard-library mechanisms. This page does not
+  claim that it is the initial source for the full reuse heuristic.
+
+### Applicable information
+
+- [Google Engineering Practices: What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
+  states that reviewers must identify the correct owner for a change. Reviewers must also verify
+  that the change agrees with the system.
+- [NIST SSDF 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) states that organizations must manage
+  and protect internal and third-party software components.
+
+### More information
+
+- [Google Engineering Practices: Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)
+  shows how APIs that no code uses can decrease change focus. Framework work that is not part of the
+  task can have the same effect.
+
+[Back to the engineering principles catalog](../README.md#p074)