oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/_shared/core/anti-ai-prose.md

@@ -0,0 +1,191 @@
+# Shared prose diagnostics
+
+Load for academic prose audits and translation style reviews, together with the
+owning skill's domain rules. Meaning, evidence, required structure, and target-language
+conventions take precedence over these style diagnostics.
+
+## Editing and review contract
+
+Read the whole passage and identify its point, audience, and existing voice. Make only
+changes that correct a supported defect. Keep useful details, uncertainty, and clear
+sentences. Do not invent facts, examples, numbers, opinions, humor, or personality to
+make writing seem more human. Reorganize only when the current order impairs understanding.
+
+In review-only mode, name the pattern, quote the affected text, explain the defect,
+and suggest a local fix. Do not rewrite the full draft or infer AI authorship from
+style. Zero findings is valid. The owning skill controls its domain report format;
+an evidence or translation-quality score is not an AI-authorship probability.
+
+Apply domain-specific exceptions; do not enforce word bans or stylistic
+preferences as universal rules.
+
+## Common patterns
+
+Target-language grammar and typography remain in the translation resource.
+Refer to patterns by heading name, not by position in this file.
+
+### Inflated significance
+
+Replace claims of importance with the supported action, result, or consequence.
+Do not describe an ordinary change as a milestone without evidence.
+
+### Superficial analysis
+
+A trailing clause such as `highlighting its importance` needs an actual explanation
+or evidence. Remove it when empty; retain substantive causal or analytical content.
+
+### Promotional tone
+
+Remove unearned praise and claims of novelty. Match the evidence and intended register.
+
+### Mannered prose
+
+Prefer a literal statement when metaphor or flourish obscures the meaning. Do not
+replace one decorative metaphor with another. The owning skill determines how to
+handle an author's intentional figurative language.
+
+### Vague attribution
+
+Identify the available source of a claim. Do not replace a named source with an
+anonymous consensus or invent a source to repair an unsupported statement.
+
+### Authority padding
+
+Keep relevant credentials and coverage only when they support a concrete claim.
+Remove unsupported prestige claims and publication lists used as praise.
+
+### Generic endings
+
+Remove formulaic optimism and redundant recaps. End with a supported result,
+limitation, implication, or next action. Preserve a required conclusion or abstract.
+
+### Vocabulary clustering
+
+Look for clusters of vague or inflated wording, including `delve`, `leverage`,
+`foster`, `pivotal`, `seamless`, `tapestry`, and `groundbreaking`. Judge the meaning
+in context; a technical term is not defective because it appears on a list.
+Language-specific examples and domain thresholds belong to the owning resource.
+
+### Unnecessary verb inflation
+
+Keep ordinary verbs such as `is`, `has`, and `uses` when accurate. Replace them only
+when a different verb states a useful distinction supported by the content.
+
+### Mechanical triples
+
+Remove stacked descriptors that repeat praise. Keep three items when each adds
+information; list length alone is not a defect.
+
+### Synonym cycling
+
+Use one term for one concept. Do not rotate labels merely to avoid repetition.
+
+### Rhetorical contrasts
+
+State the claim directly when a negative contrast or repeated negation adds only
+drama. Retain contrasts that distinguish real alternatives or necessary exclusions.
+
+### Compound adjective stacking
+
+Unpack stacked compound modifiers when they obscure what the subject does.
+Keep established technical terms and meaningful distinctions.
+
+### Abstract noun and adjective stacking
+
+Replace vague descriptive clusters with a concrete action or property already
+supported by the passage. Do not remove necessary technical precision.
+
+### False ranges
+
+Use a range only when its endpoints define a meaningful scale or scope.
+
+### Decorative bold
+
+Avoid mechanical emphasis. Use formatting that helps the reader locate information.
+
+### Decorative dashes
+
+Express the relationship between clauses with suitable grammar and punctuation.
+Do not use dashes as a repeated rhythm device. Domain and locale rules set limits.
+
+### Mechanical punctuation swaps
+
+Replacing a dash with a colon or parentheses does not repair unclear syntax.
+Rewrite the relationship when punctuation alone cannot express it.
+
+### Heading case
+
+Follow the document's required heading convention and target-language typography.
+
+### Unnecessary tables
+
+Use tables for information readers need to compare or look up, when the format allows.
+
+### Mini-heading lists
+
+Do not turn short prose into a series of bold labels and explanations without a
+reading or reference need.
+
+### Emoji decoration
+
+Do not add emoji as ornament. Preserve content or UI conventions where required.
+
+### Heading warmups
+
+Remove a sentence that merely repeats the heading before the actual content begins.
+
+### Chatbot artifacts
+
+Exclude conversational acknowledgments and offers of further help from deliverable
+prose unless they are themselves the requested content or quoted source material.
+
+### Empty metadiscourse
+
+Remove sentences telling readers a point matters when the passage already shows
+why. If the explanation is missing, provide existing evidence instead of emphasis.
+Keep uncertainty that reflects the evidence or the author's intended meaning.
+
+### Announced exposition
+
+Remove introductory announcements that delay the subject without adding context.
+Keep introductions that define scope or help readers follow a necessary transition.
+
+### Unsupported insight claims
+
+Remove claims that the writer alone sees a hidden truth. Present the argument and
+its support without asserting that everyone else missed it.
+
+### Boilerplate limitations
+
+Remove generic availability or knowledge disclaimers. Keep actual source limitations
+and uncertainty relevant to the claim.
+
+### Filler and indirect verbs
+
+Shorten empty phrases and use direct verbs where meaning survives. Preserve a
+qualifier when it carries uncertainty, emphasis, or a necessary distinction.
+
+### Mechanical rhythm
+
+Repair repeated sentence shapes when they impede reading. Preserve clear variation
+and an author's characteristic cadence. Do not impose identical paragraph shapes
+or insert fragments solely to create variation; domain structure rules still apply.
+
+### Portability test
+
+Check whether a sentence could describe an unrelated subject with only its name
+changed. If so, determine whether it adds necessary context or merely generic praise.
+Replace empty wording with an available mechanism, observation, consequence, or
+example; otherwise remove it where editing scope permits. Never fabricate detail.
+
+### Dramatic reveals and rhetorical questions
+
+Remove a question answered immediately for effect, or a label followed by a colon
+that delays a plain claim. Keep real research questions, definitions, labels, and
+structural colons when the domain allows them.
+
+### Performative endings and fragments
+
+Remove an unsupported aphorism, decorative metaphor, or sequence of punchy fragments
+at the end. Finish on a concrete sentence already supported by the passage. Preserve
+intentional source cadence in translation and required academic conclusions.

package/skills/_shared/core/api-contracts/README.md

@@ -0,0 +1,28 @@
+# API Contracts
+
+This directory owns the optional contract template, not generated API specifications. Reuse the project's existing OpenAPI, schema, or other authoritative contract before creating a parallel Markdown specification.
+
+## When a contract artifact helps
+
+Create or update a contract when a changed API boundary needs coordination between producers and consumers, or the task explicitly requests a specification. A scoped implementation against an existing contract does not require a PM task or a new document.
+
+| Artifact | Location |
+|---|---|
+| Transient coordination contract | `.agents/results/api-contracts/{domain}.md` |
+| Durable project specification, if no existing location applies | `docs/plans/contracts/{domain}.md` |
+| Reusable format example | `template.md` in this directory |
+
+Use task/session-specific domain names for independent runs that could otherwise overwrite the same transient file. Follow assigned artifact paths when supplied. Read and write with available file tools; no memory MCP is required.
+
+## Authoring and use
+
+1. Identify the authoritative schema and affected consumers. The assigned API owner can define the contract; PM involvement is useful for unresolved product requirements.
+2. Document changed operations: method/path, input fields and validation, success/error schemas, authentication and authorization, and relevant compatibility requirements.
+3. Share the contract path with affected assigned agents through the workflow's authorized coordination channel. Resolve incompatible expectations before dependent implementation. A separate approval ceremony is unnecessary when the existing contract and task already settle them.
+4. Implement and verify producer/consumer compatibility with applicable schema checks, generated clients, or integration tests. If a contract changes, update its source and affected consumers within scope.
+
+## Completion
+
+The changed boundary is explicit, consumers can use it, and applicable compatibility checks support the result. Include pagination, rate limits, timestamp formats, and migration/deprecation behavior only when relevant. Do not invent JWT authentication, CRUD endpoints, a database, or error codes merely because the template includes an example.
+
+Follow `../execution-policy.md` for authorization and verification. Transient artifacts do not belong in this source directory; durable specifications follow the repository's tracking policy.

package/skills/_shared/core/api-contracts/template.md

@@ -0,0 +1,90 @@
+# {Domain} API Contract
+
+> Author: {assigned-owner} | Session: {session-id} | Date: {YYYY-MM-DD}
+
+Use only the operations and fields needed by the actual contract. The CRUD, UUID, ownership, and pagination examples below are placeholders, not required architecture.
+
+## Base URL
+`/api/{domain}`
+
+## Authentication
+{Actual authentication scheme, public operations, and per-operation authorization rules. Preserve the project contract; do not assume JWT.}
+
+---
+
+## Endpoints
+
+### POST /api/{domain}
+- **Description**: Create a new {resource}
+- **Auth**: Required
+- **Request Body**:
+  ```json
+  {
+    "field1": "string (required)",
+    "field2": "number (optional, default: 0)"
+  }
+  ```
+- **Response 201**:
+  ```json
+  {
+    "id": "uuid",
+    "field1": "string",
+    "field2": 0,
+    "created_at": "2024-01-01T00:00:00Z"
+  }
+  ```
+- **Errors**: 401, 422
+
+### GET /api/{domain}
+- **Description**: List {resources} (paginated)
+- **Auth**: Required
+- **Query Params**: `page` (default: 1), `size` (default: 20)
+- **Response 200**:
+  ```json
+  {
+    "items": [...],
+    "total": 100,
+    "page": 1,
+    "size": 20
+  }
+  ```
+
+### GET /api/{domain}/{id}
+- **Description**: Get single {resource}
+- **Auth**: Required
+- **Response 200**: Single resource object
+- **Errors**: 401, 404
+
+### PATCH /api/{domain}/{id}
+- **Description**: Update {resource}
+- **Auth**: Required (owner only)
+- **Request Body**: Partial update fields
+- **Response 200**: Updated resource object
+- **Errors**: 401, 403, 404, 422
+
+### DELETE /api/{domain}/{id}
+- **Description**: Delete {resource}
+- **Auth**: Required (owner only)
+- **Response 204**: No content
+- **Errors**: 401, 403, 404
+
+---
+
+## Data Models
+
+### {Resource}
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | UUID | auto | Primary key |
+| field1 | string | yes | Description |
+| field2 | number | no | Default: 0 |
+| user_id | UUID | auto | Owner (FK to users) |
+| created_at | datetime | auto | ISO 8601 |
+| updated_at | datetime | auto | ISO 8601 |
+
+---
+
+## Notes
+- Pagination: offset-based (page/size)
+- Sorting: `?sort=created_at&order=desc` (optional)
+- Filtering: `?field1=value` (optional)

package/skills/_shared/core/clarification-protocol.md

@@ -0,0 +1,23 @@
+# Clarification Protocol
+
+Apply [Execution Policy](execution-policy.md) before deciding whether to ask.
+
+| Situation | Action |
+|-----------|--------|
+| Goal and authorization are clear; routine details remain | Use repository conventions, state consequential assumptions, proceed |
+| A preference could improve the result | Ask one concise optional question and continue independent work |
+| Missing information materially changes correctness or scope | Ask the specific question; pause only the dependent work |
+| An action requires authorization not already given | Prepare the reviewable result, explain the action and reason, then ask |
+
+Check prior messages, project configuration, and existing behavior before asking. The presence of tradeoffs, an existing-code conflict, or subjective wording alone is not a blocker. Do not add authentication, a database, or a framework solely because a generic checklist has a default.
+
+## Question transport
+
+- When clarification, a preference, or approval is needed, prefer the runtime's asynchronous user-question tool when available and permitted for that purpose. Otherwise use an available question tool or one concise plain-text question, respecting the runtime's mode and tool restrictions.
+- Ask one focused question at a time. For approval, first present the concrete result and explain which action needs authorization and why; the question must be understandable on its own.
+- Continue independent, authorized work while an answer is pending. Pause only the work that depends on required information or approval.
+- Silence, elapsed time, and a preselected option are not approval. Keep required questions pending until the user explicitly answers; do not repeat an unanswered question through multiple channels.
+- For an optional preference, allow a reasonable opportunity to answer, then state an assumption and proceed if necessary. An optional question must not become an approval gate.
+- Vendor execution protocols map this policy to tools exposed in the current session; do not assume every vendor provides the same tool name.
+
+Subagents report the exact missing fact and any independent work completed in a structured `blocked` or `partial` result. The coordinator answers from existing context where possible and asks the user only when necessary.

package/skills/_shared/core/code-intelligence.md

@@ -0,0 +1,46 @@
+# Code Intelligence Capability Contract
+
+Use the repository's configured `code_intelligence` capability for code search,
+navigation, impact analysis, and contract discovery. Do not name a provider as a
+requirement in a workflow or skill.
+
+## Resolve the capability
+
+1. Read the project configuration and discover the provider's actual tools.
+2. Use the configured provider when its tools are available for this repository.
+3. Do not install, initialize, track, or register a repository from an agent
+   session. Project-root tracking and exclude maintenance belong to
+   `oma install` / `oma update`; if the provider reports the repository as
+   untracked, tell the user to run `oma update`.
+4. If the provider is unavailable, has no applicable tool, or times out, use
+   native search only for paths outside this project or ignored paths, and
+   scoped reads of files already located. Do not search project source with
+   native tools as a substitute. Record the fallback and its limits in the
+   result.
+5. The `code-intelligence-guard` PreToolUse hook enforces this contract while a
+   provider is configured (`providers.code_intelligence_guard: block`, the
+   default): native `Grep` / `Glob` and recursive shell search (`rg`, `grep -r`,
+   `find -name`, `git grep`) are denied and the reason names the provider tool
+   to use. Searches whose entire scope is a confirmed exclusion or outside the
+   project already pass. The hook does not name a bypass for project source.
+
+The fallback is valid evidence when it covers the requested scope; it is not a
+reason to stop independent work or to silently switch to another provider.
+
+## State is independent of code intelligence
+
+Workflow session, progress, result, and lesson artifacts use the configured
+file-memory path from `../runtime/memory-protocol.md`. Code-intelligence MCP memory tools
+do not own those artifacts and are never required to read or write them.
+
+## Result record
+
+Record one of:
+
+```yaml
+code_intelligence:
+  provider: configured-provider | native
+  mode: available | unavailable | timeout | fallback
+  tools: [discovered_tool]
+  limitation: null | "reason native fallback was used"
+```

package/skills/_shared/core/collaboration-policy.md

@@ -0,0 +1,28 @@
+# Collaboration Policy
+
+Use when assigning or coordinating parallel worker tasks. Apply the existing execution policy, task contracts, verification, and recovery limits.
+
+## Assignment and collection
+
+- Give each worker a concrete deliverable, allowed edit paths, shared constraints, and the identities of relevant peers. Choose the worker count from the work and available parallelism.
+- Designate one existing worker to collect outputs alongside its own assigned deliverable. Keep integration edits within that worker's approved scope and workspace. Preserve each contributor's run identity and verification evidence when combining results.
+- Supply the relevant collaboration rules or this reference through the supported dispatch context so workers receive their contact and handoff instructions.
+- Required checks and QA must cover the final combined revision. Re-run affected checks and review after integration edits; the coordinator then checks the combined result and unresolved work.
+
+## Resolve issues with the responsible peer
+
+- When the host exposes direct peer messaging, use the actual recipient identity and identify the affected task/run, paths or interface, observed problem, evidence, and requested action.
+- Resolve routine interface and handoff issues with the responsible peer within the assigned contracts. If direct messaging is unavailable, ask the coordinator to relay the issue through the supported handoff path.
+- Report unresolved blockers and proposed plan or deliverable changes to the coordinator. Pause only the dependent work and continue independent assignments within the existing recovery budget.
+
+## Transfer edit ownership
+
+1. Both workers confirm the exact paths, remaining work, and current revision or patch. The work must already fit both tasks' authorized scopes and the receiving task's acceptance contract; otherwise refer it to the coordinator.
+2. The outgoing owner stops editing the agreed paths before the receiving owner starts. Record the agreement and unfinished work in each worker's own coordination notes, and notify the coordinator to update the shared task board.
+3. The receiving owner works in its assigned workspace and records its actual changes and checks under its own run identity. With separate worktrees, exchange patches or commits through the existing integration path and preserve each other's changes.
+
+If agreement or ownership is unclear, pause edits to the contested paths and involve the coordinator. Shared task boards remain coordinator-owned; each worker retains ownership of its own progress, result, and claim files.
+
+## Keep task contracts intact
+
+Peer agreement and notification do not modify a frozen plan. Changes to task identities, deliverables, scope, dependencies, or pinned checks go to the coordinator before dependent work proceeds. Follow the existing [result contract](../runtime/result-contract.md) for replanning, preserve prior outcomes and evidence, and retain the logical goal's recovery budget.

package/skills/_shared/core/common-checklist.md

@@ -0,0 +1,28 @@
+# Common Code Quality Checklist
+
+Use applicable sections for a cross-domain review. Check the changed behavior and affected boundaries; this list does not expand the task or override project checks. Authorization and verification scope follow `execution-policy.md`.
+
+## Correctness and maintenance
+- [ ] Behavior matches acceptance criteria and existing contracts.
+- [ ] Names and structure follow the project; complexity does not obscure the changed behavior.
+- [ ] No required behavior is left as a stub or unresolved task-created TODO. Existing tracked debt does not block unrelated work.
+- [ ] Generated artifacts are updated through the project's generator when required.
+
+## Error handling
+- [ ] Failure paths propagate to an appropriate handler or error boundary; no swallowed rejection or silent data loss.
+- [ ] User-facing errors are actionable without exposing internal or sensitive data.
+- [ ] Recovery, cancellation, and cleanup work where the change depends on them.
+
+## Security
+- [ ] No secrets in code, logs, error messages, or staged files.
+- [ ] Untrusted input is validated and handled safely at SQL, shell, and HTML boundaries.
+- [ ] Protected operations enforce authentication and authorization at the relevant trust boundary.
+
+## Verification
+- [ ] Tests assert affected behavior and relevant failure or boundary cases.
+- [ ] Required project checks pass, or missing evidence and its impact are reported.
+- [ ] For changes where automated tests add little value, applicable inspection or static checks support the result.
+
+## Change hygiene
+- [ ] Changes stay within scope and preserve unrelated work.
+- [ ] When committing is requested, staging follows repository rules, including whether generated artifacts are tracked.

package/skills/_shared/core/context-budget.md

@@ -0,0 +1,22 @@
+# Context Budget
+
+Keep the context relevant to the current task. Prefer scoped search and reads for large files; read a whole file when its size or the review scope makes that useful. Re-read changed content when needed to verify current behavior.
+
+## Measure actual loading
+
+`bun scripts/measure-skill-context.ts` reports file-size estimates using UTF-8 bytes / 4. It is not an Astra tokenizer or a live usage measurement. The routed tier is the entry skill; resource tiers are comparison scenarios, not instructions to preload those files. Generated vendor aliases are not independent prompt copies.
+
+Measure the assembled prompt separately when changing injection. Include the owning entry, runtime contracts, task instructions, and any references actually supplied. The runtime retains a required entry even if it exceeds its soft budget and reports the overrun. Reduce that entry or select a narrower skill; do not silently drop its contract.
+
+Use `oma skill audit` to find routing overlap and unusually large entries. Counts and thresholds are diagnostics, not proof of task utility. Keep measured summaries current rather than copying fixed claims about which skills exceed a limit.
+
+## During a task
+
+- Process bulk logs, datasets, and manifests through tools; return relevant excerpts, counts, and artifact paths.
+- Load one platform or operation at a time. Error playbooks, examples, and experimental protocols remain conditional.
+- Record important decisions and remaining work in durable state for long tasks. Do not maintain a separate file-read ledger for a trivial edit.
+- Before compaction or a restart, save completed work, remaining acceptance criteria, relevant paths, verification status, and material assumptions.
+- Continue from that checkpoint. A turn estimate or elapsed time is not completion and does not require renewed approval.
+- Restart an agent only for observed loss of useful context or stalled progress. Preserve its partial result and avoid duplicating a live attempt.
+
+Authorization and completion follow `execution-policy.md`; run/claim identity follows `../runtime/result-contract.md`.

package/skills/_shared/core/context-loading.md

@@ -0,0 +1,34 @@
+# Context Loading
+
+Read the routed skill once. Its references are an index, not a preload list.
+
+## Selecting context
+
+- Start with the task, acceptance criteria, and the owning skill's SKILL.md.
+- Read a supporting document only when its stated trigger applies. Existing project conventions take precedence over starter examples.
+- Load execution-protocol.md when its selected operation needs command, schema, or recovery detail; its existence alone is not a trigger.
+- Load only the selected framework or platform reference. Generated stack/ files describe the project; variants/ are starter material for /stack-set, not mandatory reading for existing-code edits.
+- Consult relevant checklist sections for unresolved verification requirements. Read an error playbook only for the observed failure.
+- Read difficulty-guide.md for decomposition decisions, not before every task. Difficulty does not activate extra skills or full checklists.
+- Runtime transport, authorization, and result contracts are injected once by CLI dispatch. Native agents read those contracts if not already supplied.
+
+## Conditional shared resources
+
+| Resource | Load when |
+|---|---|
+| `../conditional/quality-score.md` | The task needs a defined baseline or experiment comparison |
+| `../conditional/experiment-ledger.md` | Recording an actual experiment |
+| `../conditional/exploration-loop.md` | Repeated recovery fails on the same issue and alternative mechanisms merit testing within budget, or the user requests exploration |
+| `common-checklist.md` | A broad cross-domain review needs its applicable checks |
+| `context-budget.md` | Managing a long task or diagnosing context overhead |
+| `../runtime/memory-protocol.md` | Coordinating agents or resuming durable task state |
+
+## Runtime selection
+
+The graph records references, not permission to load them. The context loader injects the owning entry skill and defers its supporting references. Cross-routes to another specialist do not inject that specialist's body.
+
+Difficulty selects a soft size budget. If the entry skill exceeds it, retain the entry and report the overrun. Do not replace it with smaller unrelated documents. Explicitly requested supporting references are checked against the graph and loaded within the remaining budget; deferred paths remain available for scoped reads.
+
+## Subagent prompts
+
+Pass the task ID, scope, acceptance criteria, material constraints, and relevant artifact paths. Identify the owning skill by path; do not paste its body if the runtime injects it. Pass a reference or guide section only when this task needs it. Preserve injected run/claim identity. Use `prompt-structure.md` when composing an unfamiliar handoff, not as another mandatory preload.

package/skills/_shared/core/difficulty-guide.md

@@ -0,0 +1,26 @@
+# Task Decomposition
+
+Use this guide when scope or dependencies make the execution approach unclear. Routine changes do not need a difficulty report or a separate planning phase.
+
+## Choose the amount of planning
+
+| Task characteristics | Approach |
+|---|---|
+| Clear change following an existing pattern | Inspect the affected behavior, implement, and run relevant checks |
+| Several coupled changes or a material design choice | Identify dependencies and acceptance criteria; resolve the choice before dependent edits |
+| Multiple independently verifiable outcomes or uncertain boundaries | Break work into deliverables, each with its own implementation and verification |
+
+File counts and estimated turns are hints, not gates. Many repetitive file edits can be straightforward; a one-line authorization change can need careful regression testing. The CLI's Simple/Medium/Complex classifier selects a context size budget; it does not prescribe review depth or activate other agents.
+
+## Decompose around behavior
+
+- Use as many deliverables as dependencies require, without a fixed sprint count or turn quota.
+- Keep tests and error handling with the behavior they verify. For authentication plus CRUD, verify authentication with its endpoints before integrating and testing protected CRUD paths.
+- Use the project's declared checks and `test-approach.md` where applicable. A broad audit may use relevant sections of `common-checklist.md`; complexity alone does not require every check.
+- Delegate only when authorized and when independent work can proceed. Follow `skill-routing.md` for ownership, not a compulsory agent chain.
+
+## Adjust during execution
+
+If new dependencies emerge, update the remaining work and continue within the authorized scope. If the task is simpler than expected, finish without preserving unnecessary phases. For long tasks, checkpoint completed work and remaining evidence as described in `context-budget.md`.
+
+Completion and authorization follow `execution-policy.md`. A turn estimate does not end the task or require renewed approval.

package/skills/_shared/core/execution-policy.md

@@ -0,0 +1,31 @@
+# Execution Policy
+
+This is the shared OMA policy for authorization, clarification, verification, and completion. Workflows define steps; skills define domain methods; vendor protocols define transport. They refer here instead of defining different stop/approval rules. System and developer instructions and the user's current request take precedence over OMA defaults.
+
+## Authorization and clarification
+
+- Carry the user's requested work through implementation. Existing authorization persists; a plan review or proposed fix does not require another approval when that work is already authorized.
+- Resolve routine, reversible implementation choices from repository conventions. State material assumptions and continue independent work while a question is pending.
+- Ask only for information that changes the outcome or for an action outside the authorized scope. Pause only the dependent action. Before requesting new approval, prepare the concrete result for review.
+- Use the [Clarification Protocol](clarification-protocol.md) for question transport: prefer an available asynchronous question tool and keep independent work moving. Never treat silence, elapsed time, or a default selection as approval.
+- Do not infer permission to send messages, publish, spend beyond an agreed budget, destroy data, or expand scope. Conversely, do not request that permission again when explicitly granted.
+- Never build, compile, bundle, or package software until the user explicitly asks for a build. Type checking without emission and relevant tests do not authorize a build.
+
+## Resource budgets, cancellation, and monitoring
+
+- Before expensive batches, downloads, installations, or long-running subprocesses, record the execution deadline, parallelism, attempt/cost limits, and available host resource limits. Use existing configured limits and a small reversible probe when costs are unknown; preserve the requested scope and do not invent a new approval step.
+- Apply one absolute deadline to preparation, installation, execution, retries, and verification, reserving time for shutdown. Propagate the remaining budget to children and retain it across resume; a new process, task ID, or retry does not reset it. CPU, RAM, and storage limits are enforced only where the host or provider supports them. Metadata alone is not enforcement.
+- User cancellation takes precedence over completion gates and recovery. Check cancellation and the remaining deadline before every dispatch, review, verification, recovery action, and resumed admission. On cancellation or deadline exhaustion, stop admitting new work, agents, retries, failover, reviews, and verification. Allow only bounded shutdown, termination checks, and an accurate partial handoff. Do not repair a gate or replay work to keep a cancelled run alive.
+- Record resources as they are created: run identity, process identity/group, provider or container IDs, and generated file/cache paths. Stop only resources whose ownership is established. Request cancellation through the host API for native agents; use verified process-tree termination for CLI-owned workers. Retain ownership records until termination is confirmed and report any surviving resources or unsupported cancellation capability.
+- Stopping computation does not authorize deletion. Preserve logs, results, worktrees, caches, images, volumes, credentials, and user data unless deletion is requested or an explicit retention policy applies. Check shared use before removing a registered resource; never replace scoped cleanup with a global prune or name-only process kill.
+- Prefer completion notifications and host-supported waits. When polling is necessary, designate one coordinator, increase the interval within the remaining deadline, and read only changed status or short log tails. Keep cancellation delivery independent of the polling interval; avoid duplicate watchers and repeated unchanged updates.
+
+## Verification and completion
+
+- Verification belongs to the project's local CI and push hooks. Do not run test suites, type checks, linters, or builds on your own initiative; run a check only when the user or the active workflow explicitly requires it.
+- Add a regression test with a bug fix. Do not invent implementation-mirroring tests for prose or configuration edits.
+- Prefer hermetic tests. A test that needs Docker, containers (including testcontainers), or another external service is a last resort: isolate it in the project's opt-in integration task and keep it out of default hooks and required gates.
+- Use the shared [result contract](../runtime/result-contract.md) for agent handoffs. Process exit zero and a Markdown file alone are not verified completion.
+- Report completed, partial, blocked, or failed accurately, with remaining work and verification limits. A gate failure means repair evidence/work within the existing scope and retry; it is not automatically a new permission requirement.
+
+Repository check: `cli/platform/execution-policy.test.ts`.

package/skills/_shared/core/lessons-learned.md

@@ -0,0 +1,33 @@
+# Lessons Learned
+
+Consult a relevant lesson after an observed failure or when prior evidence matches the current task. This file defines lesson handling; it is not a mandatory startup read or a destination for automatic edits to installed skills.
+
+## Capture a useful lesson
+
+Record a lesson when a repeated failure, consequential incident, or requested retrospective exposes a reusable cause and prevention method. Fix and verify routine failures directly. An expected failing regression test, a clarification question, or an experiment with a lower score does not by itself require an RCA.
+
+Use the configured coordination store's `lessons-{sessionId}.md` (default `.agents/state/memories/`), or link an existing incident/result artifact. Include only information that helps prevent recurrence:
+
+- The affected session/task/run and evidence paths.
+- Observed behavior and impact; separate facts from suspected causes.
+- Relevant framework version, configuration, or operating conditions.
+- The fix and checks that support it.
+- The prevention action and when it applies.
+
+If the cause is unknown, say so. Do not invent a lesson merely to close a session. If the user says not to repeat a mistake, apply that correction to ongoing work immediately; record the reusable part without delaying the fix for a template.
+
+## Applying lessons
+
+- Check applicability against the installed version and actual configuration. A fix for one framework or runtime is not a universal rule.
+- Review generated migrations against intended schema changes; generator success alone does not establish correctness.
+- For integration failures, compare the actual producer and consumer contract: field names, types, authentication, timestamps, and error responses.
+- Verify a suspected lifecycle, hydration, or redirect defect with the failing path before prescribing a hook, wrapper, or address substitution.
+- Review findings need evidence. A disagreement alone does not establish an error; a separate reviewer does not guarantee correctness. Select runtime checks when the behavior requires them and record any verification limits.
+
+## Promoting and maintaining lessons
+
+Recurring evidence may justify a change to an owning skill, checklist, or project rule. Within an authorized source-maintenance task, prepare the scoped change, preserve exact version/trigger conditions, and verify it. Otherwise retain a proposal in the session artifact; do not mutate installed definitions during an unrelated run.
+
+Read an experiment ledger only when it exists and a result needs analysis. A negative delta is a candidate for investigation, not proof of a reusable lesson. Keep successful and failed cases when comparing a proposed rule. Archive or remove historical lessons only under the repository's retention policy or the user's direction.
+
+Use `session-metrics.md` for optional session evidence and `execution-policy.md` for authorization and completion.

package/skills/_shared/core/prompt-structure.md

@@ -0,0 +1,18 @@
+# Task Handoffs
+
+Use this guide when composing a task for another agent or when the requested outcome is unclear. A simple direct request does not need to be rewritten into a template.
+
+Include the information the recipient needs:
+
+| Element | Content |
+|---|---|
+| Goal | Observable behavior or artifact to change |
+| Context | Relevant paths, existing patterns, errors, and prior decisions |
+| Constraints | Actual scope, compatibility, ownership, and authorization boundaries |
+| Done when | Acceptance criteria and proportionate verification |
+
+Infer routine details from the request and repository. Do not invent constraints or ask the user to fill headings. Ask only about a missing fact that materially changes the result; follow `execution-policy.md` and `clarification-protocol.md`.
+
+For implementation, include affected tests or examples when they clarify the contract. For a bug, describe the failure and expected behavior. For verification, name applicable project checks; a build is included only when explicitly requested by the user.
+
+For dispatched tasks, preserve injected task/run/claim identity and required artifact paths from `../runtime/result-contract.md`. Reference the owning skill rather than pasting instructions already supplied by the runtime. Ownership and dependencies matter more than a decorative report format.

package/skills/_shared/core/quality-principles.md

@@ -0,0 +1,11 @@
+# Quality Principles
+
+Use these principles for implementation and review decisions. Authorization, clarification, verification, and completion follow `execution-policy.md`.
+
+- Establish the requested behavior from the task, repository, and relevant tests. State material assumptions; compare alternatives when an unresolved design choice changes the outcome.
+- Prefer an implementation that solves the current problem without speculative features. Preserve useful existing abstractions and project conventions; line count alone is not a reason to rewrite working code.
+- Keep edits within the requested scope. Preserve unrelated work and avoid turning an adjacent issue into an unrequested refactor.
+- Verify the affected behavior with meaningful evidence. Reproduce bugs before fixing where feasible; use characterization tests for behavior-preserving refactors. Use the project's test approach and relevant static or manual checks when appropriate.
+- Report what the evidence supports and what remains unverified. Re-run checks after relevant changes or failures, not to fill a fixed review count.
+
+`test-approach.md` defines the plan's test evidence contract. `common-checklist.md` provides optional cross-domain review prompts.