Update to Claus Argos Skill OS

{
  "name": "write-engineering-specifications",
  "description": "Create implementation-ready engineering specifications, technical design documents, feature specifications, architecture briefs, and developer or coding-agent handoffs for software systems. Use when a website, app, SaaS product, API, database, automation, AI agent, game, tool, internal system, feature, migration, refactor, integration, or technical change must be documented precisely before implementation, including scope boundaries, affected files, interfaces, states, edge cases, tests, regression checks, risks, and verifiable acceptance criteria. Do not use for writing the implementation itself unless the user also requests coding.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 305
    },
    {
      "relative_path": "assets/specification-template.md",
      "size_in_bytes": 3340
    },
    {
      "relative_path": "references/interface-and-data-contracts.md",
      "size_in_bytes": 1658
    },
    {
      "relative_path": "references/ui-specification.md",
      "size_in_bytes": 3368
    },
    {
      "relative_path": "references/verification-and-handoff.md",
      "size_in_bytes": 1899
    }
  ],
  "skill_md_contents": "---\nname: write-engineering-specifications\ndescription: Create implementation-ready engineering specifications, technical design documents, feature specifications, architecture briefs, and developer or coding-agent handoffs for software systems. Use when a website, app, SaaS product, API, database, automation, AI agent, game, tool, internal system, feature, migration, refactor, integration, or technical change must be documented precisely before implementation, including scope boundaries, affected files, interfaces, states, edge cases, tests, regression checks, risks, and verifiable acceptance criteria. Do not use for writing the implementation itself unless the user also requests coding.\n---\n\n# Engineering Specification Writer\n\nCreate a technical contract that lets a competent developer or coding agent implement the intended change without inventing product requirements, scope, architecture, or design decisions.\n\n## Establish evidence and authority\n\nBefore drafting:\n\n1. Identify the requested outcome, intended users, implementation audience, current system, and delivery format.\n2. Inspect available repositories, files, schemas, routes, interfaces, screenshots, designs, logs, tests, and existing documentation. Do not describe uninspected internals as fact.\n3. Classify information as `Verified`, `User decision`, `Proposed`, `Assumed`, `Unknown`, or `Requires approval`.\n4. Record what may change, what must remain unchanged, affected dependencies, authorization limits, and recovery requirements.\n\nWhen a missing decision materially changes behavior or architecture, stop specification of that section, state the ambiguity and impact, recommend a default if safe, and request the decision. Do not hide invented decisions inside confident technical prose.\n\n## Choose specification depth\n\n- **Contained change:** concise feature or bug-fix specification covering affected behavior, files, tests, and regression boundaries.\n- **Cross-cutting feature:** full functional, data, interface, architecture, security, observability, migration, and test specification.\n- **New system:** system context, components, data ownership, interfaces, deployment, operations, quality attributes, staged delivery, and acceptance.\n- **Migration or refactor:** before/after architecture, invariants, compatibility, sequencing, data migration, rollback, and proof of equivalence.\n- **Visual implementation:** load [ui-specification.md](references/ui-specification.md) and document every relevant state and responsive rule.\n- **API or data change:** load [interface-and-data-contracts.md](references/interface-and-data-contracts.md).\n\nScale detail to risk and complexity. Avoid both vague briefs and ceremonial documents that add no implementation value.\n\nFor visual, experiential, 3D, or representation-sensitive work, also apply the shared [false-precision policy](../../shared/expert-system/false-precision-policy.md), [observable ownership model](../../shared/expert-system/observable-ownership.md), [representation strategy contract](../../shared/expert-system/representation-strategy-contract.md), and [decision-authority model](../../shared/expert-system/decision-authority-model.md).\n\n## Audit the current state\n\nDocument only relevant existing:\n\n- system context and architecture;\n- routes, components, services, jobs, agents, data stores, and external integrations;\n- current behavior and user flow;\n- file or module ownership;\n- interfaces and dependencies;\n- constraints, known defects, risks, and protected behavior;\n- baseline tests and observable performance where available.\n\nMap each factual statement to inspected evidence using paths, symbols, route names, schema names, screenshots, or source references. Mark inaccessible areas `Not verified`.\n\n## Define requirements precisely\n\nFor each requirement assign a stable ID such as `FR-001`, `NFR-001`, or `AC-001` and include rationale, priority, dependencies, and verification method.\n\nFunctional requirements must define trigger, preconditions, behavior, inputs, validation, outputs, state changes, permissions, errors, and postconditions. Non-functional requirements must be measurable or explicitly testable; never use “fast,” “secure,” “scalable,” “modern,” or “accessible” without a threshold, standard, workload, threat, or test.\n\nMaintain traceability from problem → requirement → design element → implementation area → test → acceptance criterion.\n\n## Specify the technical design\n\nUse [specification-template.md](assets/specification-template.md) as the output skeleton and remove non-applicable sections rather than filling them with noise. Define as applicable:\n\n- system context and boundaries;\n- components and responsibilities;\n- synchronous and asynchronous flows;\n- APIs, events, schemas, state, persistence, ownership, and lifecycle;\n- authentication, authorization, secrets, privacy, and abuse controls;\n- error behavior, retries, idempotency, timeouts, rate limits, concurrency, and recovery;\n- performance budgets, capacity assumptions, caching, and degradation;\n- observability, audit logs, metrics, alerts, and support diagnostics;\n- deployment, configuration, feature flags, migrations, compatibility, rollback, and removal plan;\n- accessibility, localization, platform, browser, and device support;\n- affected files or modules and their exact intended change.\n\nUse diagrams only when relationships or sequences are materially clearer visually. Label proposed architecture as proposed; do not imply it already exists.\n\n## Control implementation scope\n\nCreate separate lists:\n\n- `Create`\n- `Modify`\n- `Preserve unchanged`\n- `Prohibited without approval`\n- `Delete or deprecate`, only when explicitly authorized\n\nFor every affected file or module state its purpose, planned change, constraints, dependencies, and associated requirement IDs. When exact paths cannot be known before implementation, specify the module or responsibility and mark path assignment as an implementation decision bounded by the documented architecture.\n\nDo not require a developer to follow a technically unsound implementation merely because an early path or library guess was made. Freeze product behavior, invariants, interfaces, and acceptance criteria; allow bounded engineering choices when evidence is insufficient, recording them in a decision log.\n\n## Define behavior and edge cases\n\nDescribe main flows as precondition → trigger → validation → processing → persistence or side effect → response → UI/system update → observability. Cover relevant empty, loading, success, partial, error, offline, timeout, retry, duplicate, concurrent, stale, unauthorized, malformed, boundary, accessibility, and recovery states.\n\nDo not create imaginary edge cases. Derive them from inputs, state transitions, dependencies, trust boundaries, and failure modes.\n\n## Build the verification contract\n\nRead [verification-and-handoff.md](references/verification-and-handoff.md). Define tests before implementation, including applicable unit, integration, contract, end-to-end, migration, performance, security, accessibility, responsive, compatibility, recovery, and regression checks.\n\nEvery acceptance criterion must be binary or objectively reviewable, identify its evidence, and trace to requirements. State the tested scope; never claim complete security, accessibility, performance, or regression coverage from a partial test.\n\n## Prepare coding-agent instructions\n\nEnd the document with an implementation directive that says:\n\n- implement only approved scope;\n- preserve named invariants and protected areas;\n- do not add features or redesign interfaces;\n- do not refactor unrelated code;\n- follow existing repository conventions unless the specification explicitly changes them;\n- surface conflicts between specification and repository evidence before proceeding;\n- when a blocking decision is missing, report the issue, affected requirement, options, and recommendation, then await approval;\n- run specified checks and report actual results without fabrication;\n- provide a concise change manifest and residual risks.\n\nThis restriction does not prohibit routine local engineering judgment such as variable naming or equivalent internal structure when it does not alter documented behavior, architecture, interfaces, risk, or scope.\n\n## Deliver\n\nProvide:\n\n1. implementation-ready specification;\n2. decision and assumption log;\n3. requirement-to-test traceability matrix;\n4. unresolved blockers and approvals;\n5. developer or coding-agent handoff prompt;\n6. source/evidence index.\n\nUse `$create-professional-documents` when the user requests a polished DOCX or PDF artifact. Use `$execute-premium-projects` only when implementation and verification are also requested; specification alone does not authorize code changes.\n\n## Single specification and suite contribution\n\n- `SINGLE SPEC` owns one contained engineering contract from evidence through document-level verification.\n- `SPEC SUITE CONTRIBUTION` authors only the artifact and decision areas assigned by an approved Documentation Blueprint from `$architect-implementation-documentation`. Preserve suite IDs, metadata, sources, boundaries, dependencies, and precedence; do not redefine the suite.\n\nUse suite-contribution mode only when the Blueprint identifies artifact, owned decisions, required inputs, target status, dependencies, and acceptance checks. Otherwise report the missing control information.\n\nDo not mark a specification `FINAL` until its declared scope is approved, decision-complete, internally consistent, reference-resolvable, and document-level verified. In a suite, document finality does not imply whole-suite readiness.\n\nFor every area ask: **Could the developer make an unauthorized Class-1 decision or exercise Class-2 judgment without an approved role, target, bounds, evidence, checkpoint, and reviewer?** If yes, record `ENTSCHEIDUNGSLÜCKE` and obtain the responsible decision.\n\nDo not freeze every visible parameter. Protect product, brand, architecture, interfaces, security, data, scope, invariants, and observable relationships with exact decisions where evidence supports them; classify the rest as `TARGET`, `BOUND`, `PROFESSIONAL_DISCRETION`, `ENGINEERING_DISCRETION`, `CALIBRATION_REQUIRED`, `VERIFY_AT_RUNTIME`, or `PERCEPTUAL_ACCEPTANCE`. A final visual specification may contain these controlled classes. Unsupported exactness is false precision, not readiness.\n\nFor important visible components define relationship specifications, one primary owner per material observable, the active representation method/status, applicable proof or remaining calibration, local checkpoints, perceptual acceptance, and independent review. List representation candidates only while the method is legitimately open; carry an applicable `METHOD_CLOSED` decision into the specification without reopening it. Correct compliance with a defective specification is not success.\n\nRecord artifact version, status, owner, date, source IDs, `extends`, `overrides`, `supersedes`, and downstream dependencies. For suite contributions, verify cross-document interfaces, terminology, versions, dependencies, and precedence. Route whole-suite readiness to `$project-specification-auditor`; never self-certify the package.\n"
}