@homericintelligence/athena-opencode 0.4.4 → 0.5.1

package/skills/myrmidon-swarm/SKILL.md

@@ -1,93 +1,168 @@
 ---
 name: myrmidon-swarm
 license: BSD-3-Clause
-description: Coordinate complex work through dependency-aware subagents in isolated worktrees, with a sequential fallback. Requires the Mnemosyne knowledge backend through advise and fails closed when it cannot be prepared.
+description: Coordinate complex work with dependency-aware subagents in isolated worktrees. Use sequential work if the host cannot delegate. This skill requires the Mnemosyne knowledge backend through advise. Stop if the backend cannot be prepared.
 argument-hint: <task description>
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
 ---
 
 # Myrmidon swarm
 
-Use this for a task with several independently useful workstreams. Do not use it for work that one
-agent can complete more clearly.
+Use this skill for a task that has multiple independent work items. Do not use it if one agent can
+complete the task clearly.
+
+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-specific rules:
+
+- [P019 — Explicit Contracts](../_support/docs/principles/README.md#p019): Give each work item explicit
+  inputs, outputs, invariants, dependencies, acceptance criteria, and failure behavior.
+- [P033 — State-Safe Failure Semantics](../_support/docs/principles/README.md#p033): If delegated work does
+  not agree with the integration base or is not satisfactory, stop integration. Keep a correct
+  coordinator tree and the delegated state necessary for recovery.
+- [P039 — Bounded Waiting](../_support/docs/principles/README.md#p039): Give each delegated or background
+  work item an applicable deadline. Record its timeout behavior or cancellation conditions.
+- [P050 — Least Privilege](../_support/docs/principles/README.md#p050): Give each work item only the tools,
+  paths, credentials, and lifetime necessary for its objective.
+- [P058 — Bounded Agent Authority](../_support/docs/principles/README.md#p058): Keep each subagent in the
+  parent task scope, mutation limits, destinations, and resource budget.
+- [P060 — Constrain Sub-Agents](../_support/docs/principles/README.md#p060): Put each writer in an isolated
+  worktree. Make sure that concurrent write sets have no common path. Before integration, validate
+  delegated output as untrusted input.
+- [P069 — Independent Review for High-Risk Changes](../_support/docs/principles/README.md#p069): If results
+  can have an effect on security or availability, find if policy or risk makes independent review
+  necessary. If independent review is necessary, use an independent reviewer. Make sure that the
+  reviewer has the necessary qualifications. Select the review scope from repository policy and
+  risk.
+- [P079 — Explicit Ownership and Lifetimes](../_support/docs/principles/README.md#p079): Record the owner of
+  each worktree, path, task, integration decision, and cleanup transition.
 
 ## Capability tiers
 
-- **Coordinator:** decomposes ambiguous or cross-cutting work and integrates results.
-- **Specialist:** handles design, investigation, review, security, or non-trivial implementation.
-- **Executor:** handles well-specified mechanical changes, focused tests, formatting, or docs.
+- A **coordinator** divides ambiguous or cross-cutting work and integrates the results.
+- A **specialist** does design, investigation, review, security, or complex implementation work.
+- An **executor** does specified mechanical changes, focused tests, formatting, or documentation.
 
-These are capability labels, not model names. Use the host's available/default model and native
-delegation, background execution, and worktree isolation capabilities. If any capability is absent,
-preserve the same ownership and dependency graph while executing the affected items sequentially in
-the coordinator.
+These terms identify capabilities. They do not identify model names. Use a model that the host makes
+available. Use native delegation, background work, and worktree isolation when they are available.
+If a capability is not available, keep the same ownership and dependency graph. Run the affected
+work sequentially in the coordinator.
 
 ## Isolation and ownership contract
 
-Before dispatch, record the integration base revision and assign every work item:
-
-- One isolated worktree based on that revision. Never let a subagent edit the coordinator's active
-  worktree or reuse a worktree owned by another agent. Use the tested
-  `../git-worktrees/scripts/prepare_worktree.py` helper by its absolute path resolved from this skill
-  directory while retaining the target repository as the current working directory. Supply an exact
-  non-overlapping `--path`, its trusted `--path-root`, and `--start-point <integration-SHA>` when the
-  host does not provide native worktree isolation.
-- An explicit file and directory ownership set. Concurrent write sets must not overlap. Shared files
-  belong to the coordinator or to one designated integration item after dependent work completes.
-- A bounded objective, dependencies, acceptance criteria, validation commands, and mutation limits.
-- A delivery format the host can integrate, such as a reviewed commit, patch, or complete read-only
-  report. The coordinator remains responsible for the final result.
-
-Read-only agents may inspect overlapping evidence, but they must not edit it. If safe isolation
-cannot be established, stop delegation and use the sequential fallback.
+Before you start subagents, record the integration base revision. For each work item:
+
+- Create one isolated worktree from the integration base revision. Do not let a subagent edit the
+  active worktree of the coordinator. Do not reuse a worktree that another agent owns. If the host
+  does not supply worktree isolation, use the tested
+  `../git-worktrees/scripts/prepare_worktree.py` helper. Resolve its absolute path from this skill
+  directory. Keep the target repository as the current working directory. Supply an exact,
+  non-overlapping `--path`, its trusted `--path-root`, and
+  `--start-point <integration-SHA>`.
+- Assign an explicit set of files and directories. Do not let concurrent write sets overlap. After
+  dependent work is complete, assign shared files to the coordinator or to one integration item.
+- Record a bounded objective, dependencies, acceptance criteria, validation commands, mutation
+  limits, granted capabilities, and a suitable stop condition. The stop condition can be a deadline,
+  a timeout, or a cancellation condition.
+- Select a delivery format that the host can integrate. Examples are a reviewed commit, a patch, or
+  a complete read-only report. The coordinator remains responsible for the final result.
+
+Read-only agents can inspect the same evidence, but they must not edit it. If the coordinator cannot
+establish safe isolation, stop delegation. In that case, use the sequential fallback.
 
 ## Workflow
 
-1. Invoke `advise` with the task description and apply relevant prior knowledge.
+1. Use `advise` to apply relevant prior knowledge to the task description.
 2. Read `AGENTS.md`, build metadata, task runners, and the files closest to the request.
-3. Decompose the work. For each item record scope, tier, files, dependencies, acceptance criteria,
-   verification, and whether it writes state.
-4. Present the plan when user approval is required by the host or task. Otherwise begin safe,
-   in-scope work.
-5. Group dependency-independent items into a wave. Start their isolated subagents as background or
-   concurrent tasks when the host supports it, up to the host's safe concurrency limit. Wait for the
-   complete wave before dispatching work that depends on it.
-6. Give each subagent its recorded worktree, ownership set, and bounded prompt. Require it to stop
-   on overlap, unexpected scope, a changed integration base, or unsafe mutation rather than
-   expanding its assignment.
-7. If background execution or delegation is unavailable, run the same items sequentially in the
-   coordinator. Do not weaken scope, isolation, validation, or evidence requirements.
-8. Review each result and its diff or evidence before integration. Reject unrelated edits and stale
-   results. Integrate accepted results sequentially onto the coordinator branch, resolving shared
-   integration files only after their producers finish.
-9. After every integration, run focused checks for the affected boundary. After the final
-   integration, run the repository-defined complete relevant validation from the combined tree.
-10. Summarize changes, verification, unresolved risks, preserved worktrees, and any learning worth
-    submitting through `learn`. `learn` must follow its own delivery boundary.
+3. Divide the work into bounded work items.
+4. For each work item, record:
+
+   - scope;
+   - capability tier;
+   - owned files;
+   - dependencies;
+   - acceptance criteria;
+   - verification;
+   - write-state status.
+
+5. If the host or task requires user approval, present the plan.
+6. Obtain each required approval before work.
+7. When all required approvals are in place, start safe work that is in scope.
+8. Group work items that do not depend on each other into one wave.
+9. If the host supports it, start isolated subagents as background or concurrent tasks.
+10. Do not exceed the safe concurrency limit of the host.
+11. Wait for the complete wave before you start work that depends on it.
+12. Give each subagent its recorded worktree, ownership set, and bounded prompt.
+13. Require each subagent to stop for overlap, unexpected scope, a changed integration base, or an
+    unsafe change.
+14. Do not let a subagent expand its assignment.
+15. If background work or delegation is not available, run the same work items sequentially in the
+    coordinator.
+16. Keep the same scope, isolation, validation, and evidence requirements during sequential work.
+17. Treat each result as untrusted input.
+18. Before integration, review the diff or evidence for each result.
+19. Reject unrelated changes and stale results.
+20. Integrate accepted results sequentially onto the coordinator branch.
+21. After all producers finish, resolve shared integration files.
+22. If repository policy or risk requires an independent review, route each security-critical or
+    availability-critical change to a qualified reviewer.
+23. Complete each review before you accept the related change.
+24. After each integration, run focused checks for the affected boundary.
+25. After the final integration, run all relevant repository validation on the combined tree.
+26. Summarize the changes, verification, unresolved risks, and preserved worktrees.
+27. In the summary, identify each useful lesson that is suitable for `learn`.
+28. If you invoke `learn`, follow its delivery boundary.
 
 ## Worktree disposition
 
-Preserve every subagent worktree until its result is integrated or explicitly rejected and the
-coordinator has proved that no unique work remains. Report the path, owner, branch or revision,
-cleanliness, and integration state.
+Preserve each subagent worktree until one of these conditions applies:
+
+- The coordinator integrates its result.
+- The coordinator explicitly rejects its result and proves that no unique work remains.
+
+For each worktree, report its path, owner, branch or revision, cleanliness, and integration state.
 
-Cleanup is a filesystem-destructive operation. Remove only worktrees created for this invocation,
-only after the user grants cleanup authority, and only after rechecking for uncommitted or
-unintegrated state. Without that authority, preserve the worktrees and return exact disposition
-information. Never delete branches, discard changes, force removal, or touch a pre-existing
-worktree.
+Cleanup is a filesystem-destructive operation. If the user grants cleanup authority, first check
+again for uncommitted or unintegrated state. Prove that no unique work remains. Then, remove only
+worktrees that this invocation created. If the user does not grant cleanup authority, preserve the
+worktrees. In that case, report their exact status. Do not delete branches. Do not discard changes. Do not
+force removal. Do not change a pre-existing worktree.
 
 ## Safety
 
-- Keep filesystem-destructive and change-discard actions behind the user's authority; keep all
-  constructive work within the requested scope and its repository safeguards.
+- Keep filesystem-destructive and change-discard actions behind the user's authority.
+- Keep constructive work within the requested scope and repository safeguards.
 - Preserve existing user changes and all pre-existing worktrees.
 - Never claim a subagent ran or a check passed without evidence.
-- Prefer the smallest number of agents that creates real parallel value.
+- Use the minimum number of agents that can do independent work in parallel.
+
+## Failed approaches
+
+- Do not let specialists write outside their worktrees or file sets.
+- Do not reuse a worktree that another agent owns.
+- Do not merge results without the disposition contract.
+- Do not remove worktrees without the disposition contract.
+- Do not remove worktrees without user cleanup authority.
+- Do not report swarm status without results, evidence, and worktree status for each specialist.
+- Do not expand a subagent assignment beyond its bounded prompt. Stop if assignments overlap.
 
 ## Status format
 
-Report each work item with its tier, dependency wave, worktree, owned paths, execution mode
-(concurrent or sequential fallback), status, result, integration revision, and verification. The
-final summary must distinguish completed work from recommendations and unresolved blockers and
-must list every preserved or removed worktree.
+For each work item, report:
+
+- capability tier;
+- dependency wave;
+- worktree;
+- owned paths;
+- execution mode, which is concurrent or sequential fallback;
+- status;
+- result;
+- integration revision;
+- verification.
+
+In the final summary, distinguish completed work from recommendations and unresolved blockers. List
+each preserved or removed worktree.

package/skills/plan-issue/SKILL.md

@@ -1,70 +1,152 @@
 ---
 name: plan-issue
 license: BSD-3-Clause
-description: Draft or publish one canonical implementation plan for a GitHub or GitLab issue after architecture and knowledge review. Use when an issue needs an executable, behavior-first plan; `--draft` is read-only.
+description: Draft or publish one canonical implementation plan for a GitHub or GitLab issue. Use this skill after architecture and knowledge review when an issue needs an executable, behavior-first plan. The `--draft` mode is read-only.
 argument-hint: "[--draft] ISSUE_NUMBER_OR_URL"
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 
 # Plan an issue
 
-Why: turn current issue requirements into the smallest architecture-aligned,
-behavior-verifiable plan before implementation begins.
+Use this skill to create the smallest architecture-aligned plan for the current issue requirements.
+Include behavior-first verification in the plan. Create the plan before implementation starts.
 
-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
+decisions:
+
+- [P010 Scope Fidelity](../_support/docs/principles/README.md#p010):
+  - Do not include work that is not in the issue.
+- [P063 Requirement-to-Code Traceability](../_support/docs/principles/README.md#p063):
+  - For each plan step, record a link to the applicable issue requirement.
+- [P012 Evidence Before Modification](../_support/docs/principles/README.md#p012):
+  - Before you put files or abstractions in the plan, examine repository evidence.
+- [P015 Architecture Conformance](../_support/docs/principles/README.md#p015):
+  - When you make the plan, obey established architecture boundaries and dependency directions.
+- [P001 KISS — Keep It Simple, Stupid](../_support/docs/principles/README.md#p001):
+  - Select the minimum solution that obeys all current requirements.
+- [P002 YAGNI — You Ain't Gonna Need It](../_support/docs/principles/README.md#p002):
+  - If a capability has no specified current requirement, do not add it.
+- [P074 Prefer Existing Mechanisms](../_support/docs/principles/README.md#p074):
+  - If an applicable existing mechanism is available, use it.
+- [P008 Understand Before Subtracting](../_support/docs/principles/README.md#p008):
+  - Before you plan a removal or consolidation, examine the mechanism's purpose, consumers, and
+    contracts.
 
 ## Scope and delivery
 
-`--draft` is read-only. A requested plan without it may publish only the
-actor-owned canonical-plan issue comment described by the issue-planning
-contract; it does not expand scope to implementation, labels, assignments, commits,
-pushes, pull requests, merges, or other forge mutations.
+`--draft` is read-only. If the request does not include `--draft`, you may publish only the
+actor-owned canonical-plan issue comment in the issue-planning contract. Do not implement code. Do
+not change labels or assignments. Do not create commits. Do not push branches. Do not create pull
+requests. Do not merge changes. Do not make other forge changes.
 
-Use the forge's native issue-comment mechanism. If it cannot safely identify or
-update the actor-owned plan, return a ready-to-publish draft and explain the
-capability or ownership gap.
+Use the native issue-comment mechanism of the forge. If the forge cannot safely identify or update
+the actor-owned plan, return a ready-to-publish draft. Explain the capability or ownership gap.
 
 ## Plan
 
-1. Resolve one exact issue in the current repository. Read its title, body,
-   labels, linked work, comments, and relevant design documents; never infer
-   requirements from a similar title.
-2. Invoke `advise` with the outcome, architecture, languages, risks, and test
-   needs. In planning mode, use its existing-checkout best-effort result without requiring upstream
-   synchronization; report its revision and trust/freshness limits, or its explicit no-guidance
-   result, and continue issue planning.
-3. Establish architecture before proposing files or abstractions: repository
-   guidance, ADRs, boundaries, dependency direction, and public interfaces.
-4. Verify current code, tests, commands, dependencies, paths, and symbols.
-   Treat the issue and earlier plan as leads, not ground truth.
-5. Map each current acceptance criterion to a minimal architecture-respecting
-   change and behavior-first validation. Exclude speculative abstractions and
-   unrelated cleanup.
-6. Follow the canonical-plan content, ownership, and identity rules in the
-   issue-planning contract. Preserve foreign content and return the draft on
-   ambiguity rather than overwriting it.
-
-When the issue body carries a valid finalized-planning marker, treat its sealed
-provenance and generated plan text as implementation-facing context, not new
-requirements. An unchanged finalized epoch needs no new plan. A later material
-issue-body edit starts a fresh requirements state and must be planned from that
-edit under the issue-planning contract.
+1. Resolve exactly one issue in the current repository.
+2. Read these sources for the issue:
+
+   - title;
+   - body;
+   - labels;
+   - linked work;
+   - comments;
+   - applicable design documents.
+
+3. Do not infer requirements from an issue that has a similar title.
+4. Invoke `advise` with the outcome, architecture, languages, risks, and test needs.
+5. In planning mode, use the best available result from the existing checkout.
+6. Do not require upstream synchronization for the planning-mode result.
+7. Report the result revision and its limits of trust and freshness.
+8. If `advise` gives an explicit no-guidance result, report that result.
+9. Continue issue planning after you report the `advise` result.
+10. Before you propose files or abstractions, establish the architecture under
+   [P015 Architecture Conformance](../_support/docs/principles/README.md#p015) from these sources:
+
+   - repository guidance;
+   - architecture decision records;
+   - boundaries;
+   - dependency direction;
+   - public interfaces.
+
+11. Under [P012 Evidence Before Modification](../_support/docs/principles/README.md#p012), verify current
+   code, tests, commands, dependencies, paths, and symbols.
+12. Treat the issue and an earlier plan as sources to verify, not as verified evidence.
+13. Under [P063 Requirement-to-Code Traceability](../_support/docs/principles/README.md#p063), map each
+    current acceptance criterion to a minimum architecture-aligned change and behavior-first
+    validation.
+14. When you compare solution sizes, apply
+    [P001 KISS — Keep It Simple, Stupid](../_support/docs/principles/README.md#p001) and
+    [P002 YAGNI — You Ain't Gonna Need It](../_support/docs/principles/README.md#p002).
+15. Prefer an applicable existing mechanism under
+    [P074 Prefer Existing Mechanisms](../_support/docs/principles/README.md#p074).
+16. Do not include speculative abstractions or unrelated cleanup.
+17. Before you delete or consolidate a mechanism, apply
+    [P008 Understand Before Subtracting](../_support/docs/principles/README.md#p008).
+18. Follow the canonical-plan content, ownership, and identity rules in the issue-planning contract.
+19. Preserve all content that another actor owns.
+20. If ownership or identity is ambiguous, return the draft.
+21. Do not overwrite content with ambiguous ownership or identity.
+
+Activate these shared profiles only for the specified surface:
+
+- For changed behavior, activate
+  [P022 Test Behavior, Not Implementation](../_support/docs/principles/README.md#p022).
+- For error contracts, activate
+  [P029 Generalize Error Policy; Preserve Specific Cause](../_support/docs/principles/README.md#p029).
+- For security or a new trust boundary, activate
+  [P048 Secure by Design](../_support/docs/principles/README.md#p048).
+
+If the issue body has a valid finalized-planning marker, use only its sealed provenance as
+implementation context. Use the generated plan text for the same purpose. Do not treat them as new
+requirements. If the finalized epoch is unchanged, do not create a new plan. If a later material
+edit changes the issue body, start a new requirements state. Plan from that edit under the
+issue-planning contract.
 
 For a material architecture decision, include or cite a
-[design record](../../docs/review/design-docs.md) that leads with why, then its
-block diagram and high-level design before clear component details. Do not
-create a durable design artifact for a simple change without a repository need.
+[design record](../_support/docs/review/design-docs.md). Start the design record with the reason for the
+decision. Then, give the block diagram and high-level design before clear component details. Do not
+create a durable design artifact for a simple change unless the repository needs it.
+
+Name only validation commands that you find in the repository. Do not claim that a command passed
+if you did not run it. Do not create a prose-string test to make the plan appear verifiable.
+Immediately before publication, resolve the canonical identity again. If the requirements, marker,
+comment, or plan content changed, withhold the update.
 
-Name only repository-discovered validation commands; never claim an unrun
-command passed or create a prose-string test to make the plan look verifiable.
-Immediately before publication, re-resolve the canonical identity and withhold
-the update if the requirements, marker, comment, or plan content drifted.
+## Failed approaches
+
+- Do not plan from the issue title alone.
+- Do not infer requirements from a similar issue.
+- Do not include an assumption before you verify paths, symbols, and commands in current repository
+  evidence. Cite the evidence as `file:line`.
+- Do not start implementation during planning.
+- Do not deliver changes beyond the canonical-plan comment.
+- Do not claim that a validation command passed if you did not run it.
+- Do not overwrite content from another actor if ownership is ambiguous.
 
 ## Result
 
-Return the issue, architecture decision, Mnemosyne revision or no-guidance status and relevant
-guidance, plan action or draft, requirement mapping, validation plan, and every unresolved decision.
-If published, return the forge URL or comment identity; otherwise state why publication was withheld.
+Return these items:
+
+- issue identity;
+- architecture decision;
+- Mnemosyne revision or no-guidance status;
+- applicable guidance;
+- plan action or draft;
+- requirement mapping;
+- validation plan;
+- each unresolved decision.
+
+If you publish the plan, return the forge URL or comment identity. If you withhold publication,
+state the reason.