@homericintelligence/athena-opencode 0.5.0 → 0.5.1

package/skills/brainstorm/SKILL.md

@@ -1,167 +1,200 @@
 ---
 name: brainstorm
 license: BSD-3-Clause
-description: Use before complex creative work to explore intent and requirements. Requires the Mnemosyne knowledge backend through advise and fails closed when it cannot be prepared.
+description: Use before complex creative work. Examine intent and requirements. Stop if `advise` cannot prepare Mnemosyne.
 argument-hint: <idea or feature description>
 allowed-tools: [Read, Write, Bash, Grep, Glob, Agent]
 ---
 
-# Brainstorming Ideas Into Designs
+# Develop designs from ideas
 
-Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+Develop a complete design and specification through a dialog with the user.
 
-Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and proceed with the requested implementation unless a requirement remains unresolved.
+Apply the [ASD-STE100 technical-English policy](../TECHNICAL_ENGLISH.md) to this skill and to all
+prose that it produces.
 
-**DESIGN CHECKPOINT:** Present a scaled design before complex implementation. It is a shared understanding checkpoint, not a permission gate; pause only for unresolved requirements or a filesystem-destructive action.
+First, inspect the current project. Ask one question in each message to clarify the idea. When the
+requirements are clear, present the design. Continue with the requested implementation unless a
+requirement remains unresolved.
+
+**DESIGN CHECKPOINT:** Before a complex implementation, present a design that has sufficient detail
+for the scope. Use this checkpoint to confirm shared understanding. It is not a permission gate.
+Stop only for an unresolved requirement or a filesystem-destructive action.
 
 ## Engineering principles
 
-Use Athena's [canonical engineering-principles catalog](../../docs/principles/README.md) as the
-definition source. Apply these principles to this workflow:
-
-- [P001 — KISS — Keep It Simple, Stupid](../../docs/principles/README.md#p001): scale the design to
-  the demonstrated problem and choose the least complex complete approach.
-- [P002 — YAGNI — You Ain't Gonna Need It](../../docs/principles/README.md#p002): exclude speculative
-  capabilities, extension points, and infrastructure from the design.
-- [P007 — Subtraction Over Addition](../../docs/principles/README.md#p007): test whether removal,
-  consolidation, or reuse solves the need before proposing a new moving part.
-- [P008 — Understand Before Subtracting](../../docs/principles/README.md#p008): inspect purpose,
-  consumers, and history before recommending deletion.
-- [P012 — Evidence Before Modification](../../docs/principles/README.md#p012): ground alternatives in
-  repository code, contracts, tests, history, and guidance before selecting a design.
-- [P015 — Architecture Conformance](../../docs/principles/README.md#p015): follow established
-  boundaries and dependency direction unless the requirement deliberately changes them.
-- [P071 — Consistency Over Personal Preference](../../docs/principles/README.md#p071): prefer repository
-  conventions over stylistic preference when they satisfy the requirement.
-- [P074 — Prefer Existing Mechanisms](../../docs/principles/README.md#p074): reuse a suitable existing
-  mechanism before inventing another one.
+Use Athena's [canonical engineering-principles catalog](../_support/docs/principles/README.md) as the
+definition source. Use these principles to make workflow decisions:
+
+- [P001 — KISS — Keep It Simple, Stupid](../_support/docs/principles/README.md#p001): Make the design
+  sufficient for the problem that the evidence shows. Select the minimum solution that obeys
+  all requirements.
+- [P002 — YAGNI — You Ain't Gonna Need It](../_support/docs/principles/README.md#p002): Do not include a
+  capability, extension point, or infrastructure that has no specified current requirement.
+- [P007 — Subtraction Over Addition](../_support/docs/principles/README.md#p007): Before you recommend a new
+  component, find if removal, consolidation, or an existing mechanism can give the necessary
+  result.
+- [P008 — Understand Before Subtracting](../_support/docs/principles/README.md#p008): Before you recommend
+  deletion, examine the purpose, consumers, and history of the applicable component.
+- [P012 — Evidence Before Modification](../_support/docs/principles/README.md#p012): Before you select a
+  design, use repository code, contracts, tests, history, and guidance as evidence.
+- [P015 — Architecture Conformance](../_support/docs/principles/README.md#p015): If the requirement does
+  not change the architecture, obey the established boundaries and dependency direction.
+- [P071 — Consistency Over Personal Preference](../_support/docs/principles/README.md#p071): If repository
+  conventions obey the requirement, use them. Do not select a different style because of
+  personal preference.
+- [P074 — Prefer Existing Mechanisms](../_support/docs/principles/README.md#p074): Before you make a
+  mechanism, find an applicable existing mechanism. If it obeys the requirement, use it.
 
 ## Failed approaches
 
-Every feature goes through this process. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences), and should make assumptions and constraints visible before implementation.
+Use this process for each feature. A short design can be sufficient for a simple change. Before
+implementation, the design must show its assumptions and constraints.
 
-- Skipping `advise` retrieval before design proposes what already exists or was already debugged.
+- Do not skip `advise` retrieval. Without this retrieval, the design can duplicate an existing
+  solution or repeat a problem that prior guidance already resolved.
 
 ## Checklist
 
 Complete in order:
 
-1. **Run `advise`** with the feature description to check the required knowledge backend.
-2. **Explore project context** — check files, docs, recent commits
-3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
-4. **Propose 2-3 approaches** — with trade-offs and your recommendation
-5. **Present design** — in sections scaled to their complexity; ask only to resolve material ambiguity
-6. **Persist when needed** — write `docs/specs/YYYY-MM-DD-<topic>-design.md` only when complexity,
-   project policy, or a current downstream consumer requires a durable specification
-7. **Design self-review** — scan for placeholders, contradictions, ambiguity, and scope issues
-8. **User confirms the design** — request file review only when a specification was persisted
-9. **Transition to implementation** — invoke `myrmidon-swarm` for complex implementation. If an
-   installed planning skill is available, it may track the approved design; otherwise write a short
-   numbered implementation plan in the current conversation and proceed sequentially.
-
-## The Process
-
-**Understanding the idea:**
-
-- Check out the current project state first (files, docs, `git log --oneline -10`)
-- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems, flag this immediately. Help the user decompose into sub-projects first.
-- For appropriately-scoped projects, ask questions one at a time
-- Prefer multiple choice questions when possible
-- Only one question per message
-- Focus on: purpose, constraints, success criteria
-
-**Exploring approaches:**
-
-- Propose 2-3 different approaches with trade-offs
-- Lead with your recommended option and explain why
-- Reference existing patterns in the target codebase
-
-**Presenting the design:**
-
-- Present in sections, ask after each whether it looks right
-- Scale each section to its complexity
-- Cover: architecture, components, data flow, error handling, testing strategy
-- Define component responsibilities and boundaries using
-  [P004 — SOLID](../../docs/principles/README.md#p004),
-  [P005 — Modularity](../../docs/principles/README.md#p005),
-  [P016 — Separation of Concerns](../../docs/principles/README.md#p016),
-  [P017 — High Cohesion, Low Coupling](../../docs/principles/README.md#p017), and
-  [P018 — Information Hiding](../../docs/principles/README.md#p018).
-- Make interfaces predictable by documenting observable inputs, outputs, errors, and invariants with
-  [P006 — POLA — Principle of Least Astonishment](../../docs/principles/README.md#p006),
-  and [P019 — Explicit Contracts](../../docs/principles/README.md#p019).
-- Identify critical architecture rules that need automated enforcement under
-  [P020 — Executable Architecture](../../docs/principles/README.md#p020), and stage the design as
-  reversible increments with explicit migration or rollback boundaries under
-  [P021 — Evolutionary and Reversible Design](../../docs/principles/README.md#p021).
-- Separate decisions from machinery and identify authoritative state and cleanup through
-  [P077 — Separate Policy from Mechanism](../../docs/principles/README.md#p077),
-  [P078 — Single Source of Truth](../../docs/principles/README.md#p078), and
-  [P079 — Explicit Ownership and Lifetimes](../../docs/principles/README.md#p079).
-- Challenge additions with [P007](../../docs/principles/README.md#p007) and
-  [P008](../../docs/principles/README.md#p008); remove verified dead code and obsolete scaffolding
-  under [P088](../../docs/principles/README.md#p088) and
-  [P089](../../docs/principles/README.md#p089), preferring
-  [P090 — Prefer Negative Code](../../docs/principles/README.md#p090) only among equally correct
-  designs.
-- Bound the proposal to the stated goal with
-  [P010 — Scope Fidelity](../../docs/principles/README.md#p010), then select the smallest complete
-  evidence-backed change with [P011 — Minimal Coherent Change](../../docs/principles/README.md#p011)
-  and [P012 — Evidence Before Modification](../../docs/principles/README.md#p012).
-- Prefer a reusable mechanism under
-  [P009 — General Mechanisms Over Special Cases](../../docs/principles/README.md#p009) only when
-  current repeated cases demonstrate it; use
-  [P013 — AHA — Avoid Hasty Abstractions](../../docs/principles/README.md#p013) to defer an unstable
+1. **Advise retrieval.** Run `advise` with the feature description to check the required knowledge
+   backend.
+2. **Project evidence.** Read applicable files, documents, and recent commits.
+3. **Clarification.** Ask one question in each message to identify the purpose, constraints, and
+   success criteria.
+4. **Approach options.** Propose two or three approaches.
+5. **Trade-offs.** State the trade-offs for each approach.
+6. **Recommendation.** Identify your recommended approach.
+7. **Design presentation.** Present sections that have sufficient detail for their complexity.
+8. **Material ambiguity.** Ask a question only to resolve a material ambiguity.
+9. **Durable specification.** Write `docs/specs/YYYY-MM-DD-<topic>-design.md` only if complexity,
+   project policy, or a current downstream consumer requires it.
+10. **Design review.** Check the design for placeholders, contradictions, ambiguities, and scope
+    errors.
+11. **Saved path.** If you saved a specification, report its path.
+12. **User review.** Ask the user to review a saved specification.
+13. **Continuation.** Do not stop unless a requirement remains unresolved.
+14. **Implementation.** Start the requested implementation.
+15. **Complex work.** For a complex implementation, invoke `myrmidon-swarm`.
+16. **Planning skill.** If an installed planning skill is available, use it to track the design.
+17. **Planning fallback.** Otherwise, write a short numbered plan in the current conversation.
+18. **Sequential work.** Complete the fallback plan in sequence.
+
+## Process
+
+### Understand the idea
+
+- First, inspect the current project files, documents, and `git log --oneline -10`.
+- Before you ask detailed questions, assess the scope.
+- If the request contains multiple independent subsystems, tell the user immediately. Help the user
+  divide the request into subprojects.
+- If the project has a suitable scope, ask questions one at a time.
+- Use multiple-choice questions when possible.
+- Ask only one question in each message.
+- Ask about the purpose, constraints, and success criteria.
+
+### Compare approaches
+
+- Propose two or three different approaches with trade-offs.
+- Put your recommended option first. Explain the reason for the recommendation.
+- Refer to existing patterns in the target codebase.
+
+### Present the design
+
+- Present the design in sections. Ask after each section if it is correct.
+- Give each section sufficient detail for its complexity.
+- Include architecture, components, data flow, error handling, and the test strategy.
+- Use these principles to define component responsibilities and boundaries:
+  [P004 — SOLID](../_support/docs/principles/README.md#p004),
+  [P005 — Modularity](../_support/docs/principles/README.md#p005),
+  [P016 — Separation of Concerns](../_support/docs/principles/README.md#p016),
+  [P017 — High Cohesion, Low Coupling](../_support/docs/principles/README.md#p017), and
+  [P018 — Information Hiding](../_support/docs/principles/README.md#p018).
+- Use [P006 — POLA — Principle of Least Astonishment](../_support/docs/principles/README.md#p006) and
+  [P019 — Explicit Contracts](../_support/docs/principles/README.md#p019) to make interfaces predictable.
+  Document observable inputs, outputs, errors, and invariants.
+- Use [P020 — Executable Architecture](../_support/docs/principles/README.md#p020) to identify critical
+  architecture rules that need automated enforcement. Use
+  [P021 — Evolutionary and Reversible Design](../_support/docs/principles/README.md#p021) to divide the
+  design into reversible increments. Specify the migration and rollback boundaries.
+- Use [P077 — Separate Policy from Mechanism](../_support/docs/principles/README.md#p077) to separate
+  decisions from machinery. Use
+  [P078 — Single Source of Truth](../_support/docs/principles/README.md#p078) to identify the authoritative
+  state. Use [P079 — Explicit Ownership and Lifetimes](../_support/docs/principles/README.md#p079) to
+  identify ownership and cleanup.
+- Use [P007](../_support/docs/principles/README.md#p007) and
+  [P008](../_support/docs/principles/README.md#p008) to question additions. Use
+  [P088](../_support/docs/principles/README.md#p088) and
+  [P089](../_support/docs/principles/README.md#p089) to remove verified dead code and obsolete scaffolding.
+  If designs are equally correct, give preference to
+  [P090 — Prefer Negative Code](../_support/docs/principles/README.md#p090).
+- Use [P010 — Scope Fidelity](../_support/docs/principles/README.md#p010) to keep the proposal in the stated
+  goal. Then use [P011 — Minimal Coherent Change](../_support/docs/principles/README.md#p011) and
+  [P012 — Evidence Before Modification](../_support/docs/principles/README.md#p012) to select the smallest
+  complete change that the evidence supports.
+- Use [P009 — General Mechanisms Over Special Cases](../_support/docs/principles/README.md#p009) only if
+  current repeated cases show the need for a reusable mechanism. Use
+  [P013 — AHA — Avoid Hasty Abstractions](../_support/docs/principles/README.md#p013) to delay an unstable
   abstraction.
-- Enumerate behavior outside the requested change and preserve it under
-  [P014 — Preserve Unrequested Behavior](../../docs/principles/README.md#p014).
+- Identify behavior that is outside the requested change. Preserve it under
+  [P014 — Preserve Unrequested Behavior](../_support/docs/principles/README.md#p014).
 
-**Working in existing codebases:**
+### Work in existing codebases
 
-- Follow existing patterns in the target repository
-- Invoke the `advise` skill first to check for existing implementations
-- Don't propose unrelated refactoring — stay focused on the current goal
+- Follow existing patterns in the target repository.
+- Invoke `advise` first to check for existing implementations.
+- Do not propose unrelated refactoring. Keep the work in the current goal.
 
-## After the Design
+## After the design
 
-**Persist a spec only when required:**
+### Save a specification only when necessary
 
-For small changes, keep the approved design in the conversation and proceed. When complexity,
-project policy, or a current downstream consumer requires a durable specification, save it to
-`docs/specs/YYYY-MM-DD-<topic>-design.md` and commit it as
+For a small change, keep the design in the conversation. Then, continue with the requested
+implementation. If complexity, project policy, or a current downstream consumer requires a durable
+specification, save it to
+`docs/specs/YYYY-MM-DD-<topic>-design.md`. Use this commit message:
 `docs(specs): add <topic> design document`.
 
-Before writing or committing a specification, read the target repository's mutation, signing, DCO,
-and review policy. A specification that is in scope may be written and committed without a separate
-approval prompt; retain it in the conversation when a durable artifact is not needed.
+Before you write or commit a specification, read the target repository policies for mutation,
+signing, the Developer Certificate of Origin (DCO), and review. If the specification is in scope,
+you can write it without a separate approval prompt. After you write an in-scope specification, you
+can commit it without a separate approval prompt. If a durable artifact is not necessary, keep the
+specification in the conversation.
+
+### Review the specification
+
+1. **Find placeholders.** Search for `TBD`, `TODO`, and incomplete sections.
+2. **Correct placeholders.** Correct each item that the search finds.
+3. **Check consistency.** Correct each conflict between sections.
+4. **Check the scope.** Make sure that one plan can contain the work.
+5. **Select one meaning.** If a requirement has two possible meanings, select one meaning.
+6. **State the meaning.** State the selected meaning clearly.
 
-**Spec Self-Review:**
+### Report the specification
 
-1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections? Fix them.
-2. **Internal consistency:** Do any sections contradict each other?
-3. **Scope check:** Is this focused enough for a single plan?
-4. **Ambiguity check:** Can any requirement be interpreted two ways? Pick one and make it explicit.
+After you review a saved specification, report its location. Continue with the requested
+implementation unless the user requests changes. Use this message:
 
-**User Review:**
-After self-review of a persisted specification, report its location and proceed with the requested
-implementation unless the user requests changes:
-> "Spec written and committed to `docs/specs/<filename>`. Please review and let me know if you want changes before we start planning implementation."
+> I wrote and committed the specification at `docs/specs/<filename>`. Review it and tell me if you
+> want changes.
 
-**Implementation:**
+### Implement the design
 
-- Use an installed planning skill for task tracking, or write the numbered plan inline when none is
-  installed.
-- Invoke the `myrmidon-swarm` skill for complex multi-agent work.
+- If a planning skill is installed, use it to track the task. Otherwise, write the numbered plan in
+  the conversation.
+- For complex multi-agent work, invoke `myrmidon-swarm`.
 
-## Working rules
+## Rules
 
-- **One question at a time** — don't overwhelm with multiple questions
-- **Apply [P002 — YAGNI — You Ain't Gonna Need It](../../docs/principles/README.md#p002)** — remove
-  unnecessary features from
-  all designs
-- **Explore alternatives** — always propose 2-3 approaches
-- **Incremental validation** — present design sections and resolve material ambiguity before moving on
-- **Invoke `advise` first** — don't propose what's already been built or debugged
+- **Ask one question at a time.** Do not put multiple questions in one message.
+- **Apply [P002 — YAGNI — You Ain't Gonna Need It](../_support/docs/principles/README.md#p002).** Remove
+  unnecessary features from all designs.
+- **Compare alternatives.** Always propose two or three approaches.
+- **Validate in increments.** Present the design in sections. Resolve material ambiguity before you
+  continue.
+- **Invoke `advise` first.** Do not duplicate an existing solution. Do not repeat a problem that prior
+  guidance already resolved.
 
 ---
 

package/skills/change-review/SKILL.md

@@ -1,104 +1,124 @@
 ---
 name: change-review
 license: BSD-3-Clause
-description: Review only the working-tree, staged, or explicit-range changes for architecture alignment, behavior, language practices, and evidence. Use before committing or opening a PR; it never edits source or posts forge comments. An ambiguous, unresolvable, or out-of-scope change set blocks the review with a reported reason instead of being silently widened.
+description: Review only a worktree, staged, or explicit-range change for architecture, behavior, language, and evidence. Use before a commit or pull request. This skill is read-only. If the scope is ambiguous, unresolved, or out of scope, report the reason. In that case, stop.
 argument-hint: "[--worktree | --staged | --range BASE..HEAD] [PATH ...]"
 allowed-tools: [Read, Bash, Grep, Glob, Agent]
 ---
 
 # Change review
 
-Why: bind the exact local change before review so findings apply to the bytes
-that will be committed.
+Purpose: Bind the exact local change to the review. Findings must apply only to the selected
+content.
 
-Use the shared [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 [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
 
-Apply the canonical [engineering-principles catalog](../../docs/principles/README.md) through these
+Use the canonical [engineering-principles catalog](../_support/docs/principles/README.md) to make these
 review decisions:
 
-- [P010 Scope Fidelity](../../docs/principles/README.md#p010) and
-  [P066 Preserve Existing Work](../../docs/principles/README.md#p066) bind the review to the selected
-  bytes without substituting another scope or disturbing unrelated work.
-- [P012 Evidence Before Modification](../../docs/principles/README.md#p012),
-  [P063 Requirement-to-Code Traceability](../../docs/principles/README.md#p063), and
-  [P072 Technical Evidence Over Preference](../../docs/principles/README.md#p072) require each
-  finding to connect inspected evidence to a requirement, contract, or demonstrated risk rather than
-  reviewer taste.
-- [P014 Preserve Unrequested Behavior](../../docs/principles/README.md#p014) and
-  [P022 Test Behavior, Not Implementation](../../docs/principles/README.md#p022) make observable
-  behavior the review target, while
-  [P065 Verify Before Claiming Completion](../../docs/principles/README.md#p065) keeps validation and
-  coverage claims bounded by evidence actually obtained.
-
-This skill is read-only. It never edits source, stages files, creates Git
-state, posts forge content, opens issues, or writes review notes into source.
+- [P010 Scope Fidelity](../_support/docs/principles/README.md#p010): Examine only the selected bytes. Do not
+  use a different scope.
+- [P066 Preserve Existing Work](../_support/docs/principles/README.md#p066): Do not change work outside the
+  selected scope.
+- [P012 Evidence Before Modification](../_support/docs/principles/README.md#p012): Before you report a
+  finding, examine the applicable evidence.
+- [P063 Requirement-to-Code Traceability](../_support/docs/principles/README.md#p063): For each finding,
+  find the applicable requirement or contract.
+- [P072 Technical Evidence Over Preference](../_support/docs/principles/README.md#p072): Give evidence that
+  you examined for each finding. Find the risk that this evidence shows. Do not use reviewer
+  preference as evidence.
+- [P014 Preserve Unrequested Behavior](../_support/docs/principles/README.md#p014): Do not recommend a
+  behavior change that the request does not include.
+- [P022 Test Behavior, Not Implementation](../_support/docs/principles/README.md#p022): Examine observable
+  behavior. Do not make tests of private implementation details necessary.
+- [P065 Verify Before Claiming Completion](../_support/docs/principles/README.md#p065): Make validation and
+  coverage claims only from evidence that you examined.
+
+This skill is read-only. Do not edit source. Do not stage files. Do not make Git state.
+
+Do not post forge content. Do not open issues. Do not write review notes into source.
 
 ## Bind the scope
 
-Choose exactly one scope:
+Select exactly one scope:
+
+- Use `--worktree` by default. It selects tracked differences from `HEAD` and non-ignored untracked
+  files.
+- Use `--staged` to select index changes from `HEAD`.
+- Use `--range BASE..HEAD` to select the explicit Git range.
+
+Before you inspect content, resolve the installed
+[`scripts/resolve_scope.py`](scripts/resolve_scope.py) from this skill directory. Read each eligible
+object in its manifest. Follow the
+[scope-resolution safety contract](references/scope-resolution.md). Use path arguments only to
+reduce the selected diff. Make sure that each path remains inside the repository root.
 
-- `--worktree` (default): tracked differences from `HEAD` and non-ignored
-  untracked files;
-- `--staged`: index changes from `HEAD`; or
-- `--range BASE..HEAD`: the explicit Git range.
+For a range, report the immutable base and head commits. For worktree or staged scope, report these
+items:
 
-Resolve the installed [`scripts/resolve_scope.py`](scripts/resolve_scope.py)
-from this skill directory before inspection. Read every eligible object in its
-manifest and follow the [scope-resolution safety contract](references/scope-resolution.md).
-Paths further restrict the selected diff and must remain inside the repository
-root.
+- `HEAD`;
+- selected paths; and
+- the returned content-bound digest.
 
-For a range, report immutable base and head commits. For worktree or staged
-scope, report `HEAD`, selected paths, and the returned content-bound digest;
-never create a commit, tree, stash, temporary index, or other Git state to
-invent a head. Report an empty scope and never silently substitute a different
-range.
+Do not create a commit, tree, stash, temporary index, or other Git state to represent a nonexistent
+head. If the scope is empty, report the empty scope. Do not substitute a different range.
 
-`--staged` and `--range` exclude untracked worktree files. State that boundary
-in the result. If resolution cannot safely cover the selected scope, report the
-coverage gap and narrow the paths or choose a safer scope; never sample it.
+`--staged` and `--range` exclude untracked worktree files. State this boundary in the result. If
+resolution cannot safely cover the selected scope, report the coverage gap. Reduce the paths.
+Alternatively, select a safer scope. Do not inspect a sample of the scope.
 
 ## Review and deliver
 
-Follow the shared review flow: establish architecture first, classify only
-applicable surfaces and language profiles, inspect changed behavior and tests,
-then de-duplicate severity-ranked evidence. Record each skipped check as N/A
-with its reason.
+Follow this shared review flow:
+
+1. Establish the architecture.
+2. Select only applicable surfaces and language profiles.
+3. Inspect changed behavior and tests.
+4. Prepare unique findings in severity order.
+
+For each skipped check, record not applicable (`N/A`). Give the reason for that status.
+
+Activate a shared profile only if the selected change contains its surface:
 
-Activate the shared profiles only when the selected change contains the relevant surface: use
-[P001 KISS — Keep It Simple, Stupid](../../docs/principles/README.md#p001) for added complexity,
-[P015 Architecture Conformance](../../docs/principles/README.md#p015) for boundary or dependency
-changes, [P022 Test Behavior, Not Implementation](../../docs/principles/README.md#p022) for testable
-behavior, [P029 Generalize Error Policy; Preserve Specific Cause](../../docs/principles/README.md#p029)
-for error-path changes, and [P048 Secure by Design](../../docs/principles/README.md#p048) for security
-or trust-boundary changes.
+- Use [P001 KISS — Keep It Simple, Stupid](../_support/docs/principles/README.md#p001) for added complexity.
+- Use [P015 Architecture Conformance](../_support/docs/principles/README.md#p015) for boundary or dependency
+  changes.
+- Use [P022 Test Behavior, Not Implementation](../_support/docs/principles/README.md#p022) for testable
+  behavior.
+- Use
+  [P029 Generalize Error Policy; Preserve Specific Cause](../_support/docs/principles/README.md#p029) for
+  error-path changes.
+- Use [P048 Secure by Design](../_support/docs/principles/README.md#p048) for security or trust-boundary
+  changes.
 
-For a material architecture change, require a stated design decision, ADR, or
-[design record](../../docs/review/design-docs.md). Missing architecture evidence
-is a blocker; do not invent it.
+For a material architecture change, require a stated design decision, architecture decision record
+(ADR), or [design record](../_support/docs/review/design-docs.md). If architecture evidence is missing,
+report a blocking finding. Do not invent evidence.
 
-Return in the console or host-native read-only annotation surface:
+Include these items in the console or host-native read-only annotation surface:
 
-1. scope identity, base/head or manifest digest, and files read;
-2. architecture decision first, then applicable and N/A checks;
-3. severity-ranked findings with exact `path:line`, impact, evidence, and a
-   proportionate remediation direction;
-4. behavior-first testing and validation coverage; and
-5. residual risks and unverified assumptions.
+1. Identify the scope, base and head or manifest digest, and files read.
+2. Give the architecture decision first.
+3. List applicable and `N/A` checks.
+4. Give severity-ranked findings with the exact `path:line`, impact, and evidence.
+5. For each finding, give a correction that is proportional to the impact.
+6. Give behavior-first test and validation coverage.
+7. Give residual risks and unverified assumptions.
 
-Use native source annotations only for changed locations when the host supports
-them. Otherwise use `path:line` in the console; never simulate annotations by
-editing source.
+If the host supports native source annotations, use them only for changed locations. Otherwise, use
+`path:line` in the console. Do not simulate annotations by editing source.
 
 ## Failed approaches
 
-- Reviewing uncommitted work as if it were committed, or inventing a head commit to bind a range.
-- Widening scope past the requested range, paths, or selected diff instead of reporting the
-  boundary.
-- Editing source, staging files, posting forge comments, or simulating native annotations to deliver
-  findings.
-- Sampling an unsafe-to-cover scope instead of reporting the coverage gap and narrowing the paths.
+- Do not review uncommitted work as if it is committed. Do not invent a head commit to bind a range.
+- Do not increase the scope beyond the requested range, paths, or selected diff. Report the boundary.
+- Do not edit source. Do not stage files. Do not publish forge comments. Do not simulate native
+  annotations to deliver findings.
+- Do not sample a scope that you cannot cover safely. Report the coverage gap. Then, reduce the paths.