From daeea26da191b5f753d32884db2476800613c81c Mon Sep 17 00:00:00 2001 From: Okiki Ojo Date: Sun, 12 Jul 2026 16:32:34 -0400 Subject: [PATCH] refactor: deno software skill references and improve validation processes - Removed unnecessary descriptions and applyTo fields from testing, TypeScript, web, and workflow references. - Enhanced the Delivery Validator and Verifier documentation for clarity on validation and verification processes. - Introduced a standalone fallback reference for Deno delivery workflow when the deliver-software skill is unavailable. - Updated audit and validate scripts to improve structure and validation checks for required files and links. - Modified CI template to use `deno ci` for dependency management instead of `deno install --frozen`. - Added new sections in various references to outline contents and improve organization. Signed-off-by: Okiki Ojo --- skills/deliver-software/SKILL.md | 8 + skills/deliver-software/agents/openai.yaml | 14 +- skills/deliver-software/references/astro.md | 4 - skills/deliver-software/references/base.md | 16 +- .../deliver-software/references/benchmarks.md | 4 - skills/deliver-software/references/changes.md | 4 - .../deliver-software/references/comments.md | 4 - skills/deliver-software/references/commits.md | 4 - .../references/composition.md | 7 - .../deliver-software/references/delivery.md | 53 +-- .../deliver-software/references/diagrams.md | 4 - skills/deliver-software/references/docs.md | 4 - .../references/implementer.md | 19 +- skills/deliver-software/references/planner.md | 32 +- skills/deliver-software/references/pulls.md | 4 - skills/deliver-software/references/python.md | 4 - skills/deliver-software/references/react.md | 4 - .../deliver-software/references/refactors.md | 63 ++++ .../deliver-software/references/releases.md | 56 +++ skills/deliver-software/references/review.md | 4 - skills/deliver-software/references/solid.md | 4 - skills/deliver-software/references/testing.md | 4 - .../deliver-software/references/typescript.md | 4 - .../deliver-software/references/validator.md | 25 +- .../deliver-software/references/verifier.md | 10 +- skills/deliver-software/references/web.md | 4 - .../deliver-software/references/workflow.md | 26 +- skills/deno-software/SKILL.md | 335 +---------------- skills/deno-software/agents/openai.yaml | 22 +- .../references/01-foundations.md | 11 + .../deno-software/references/02-releases.md | 14 + .../deno-software/references/04-packages.md | 17 + .../deno-software/references/05-workspaces.md | 18 + .../deno-software/references/06-security.md | 23 +- .../deno-software/references/09-libraries.md | 23 +- .../references/13-command-reference.md | 6 + .../deno-software/references/16-standalone.md | 338 ++++++++++++++++++ skills/deno-software/scripts/audit.ts | 44 +-- skills/deno-software/scripts/validate.ts | 22 +- skills/deno-software/templates/ci.yml | 2 +- 40 files changed, 732 insertions(+), 532 deletions(-) create mode 100644 skills/deliver-software/references/refactors.md create mode 100644 skills/deliver-software/references/releases.md create mode 100644 skills/deno-software/references/16-standalone.md diff --git a/skills/deliver-software/SKILL.md b/skills/deliver-software/SKILL.md index c089d7f..8870e84 100644 --- a/skills/deliver-software/SKILL.md +++ b/skills/deliver-software/SKILL.md @@ -42,6 +42,7 @@ framework's reference. | --- | --- | | Code, architecture, API design, refactor, or migration | [general.md](references/general.md) | | Substantial plan, implementation, refactor, migration, completion audit, or multi-surface change | [workflow.md](references/workflow.md) and [delivery.md](references/delivery.md) | +| Refactor, migration, cutover, compatibility window, or legacy removal | [refactors.md](references/refactors.md) | | Deno, TypeScript, or TSX | [typescript.md](references/typescript.md) | | Python | [python.md](references/python.md) | | Tests or test design | [testing.md](references/testing.md) | @@ -52,6 +53,7 @@ framework's reference. | Commit messages or commit plans | [commits.md](references/commits.md) | | Pull request titles, descriptions, or merge summaries | [pulls.md](references/pulls.md) | | Changelogs or release notes | [changes.md](references/changes.md) | +| Package or product release execution | [releases.md](references/releases.md) | | ASCII diagrams in docs, comments, or explanations | [diagrams.md](references/diagrams.md) | | Any browser-facing interface | [web.md](references/web.md) | | React, Next.js, Remix, or React Router UI | [react.md](references/react.md) | @@ -183,6 +185,12 @@ or other user-facing capability whenever the environment permits it. Record the exact workflow and observed behavior. Use tests and static checks as supporting evidence, not substitutes for an executable workflow that can be run. +Before verification mutates state, identify the exact target, data and +credential owner, external messages or charges, reversibility, rollback, +cleanup, and whether the request authorizes that consequence. A request to +change migration, deployment, release, notification, or billing code does not +implicitly authorize running it against ambient production credentials. + If the capability cannot be run, name the concrete blocker and the remaining verification steps. Never label an unrun capability verified. diff --git a/skills/deliver-software/agents/openai.yaml b/skills/deliver-software/agents/openai.yaml index 6104b98..53572f7 100644 --- a/skills/deliver-software/agents/openai.yaml +++ b/skills/deliver-software/agents/openai.yaml @@ -1,12 +1,4 @@ interface: - display_name: Deliver Software - short_description: Plan, implement, and verify code thoroughly - default_prompt: Use $deliver-software to plan, implement, and verify this codebase - change to completion. -policy: - products: - - chatgpt - - codex - - api - - atlas - allow_implicit_invocation: true + display_name: "Deliver Software" + short_description: "Plan, implement, and verify software completely" + default_prompt: "Use $deliver-software to complete and verify this software task." diff --git a/skills/deliver-software/references/astro.md b/skills/deliver-software/references/astro.md index e8e0177..9a77113 100644 --- a/skills/deliver-software/references/astro.md +++ b/skills/deliver-software/references/astro.md @@ -1,7 +1,3 @@ ---- -description: Write and review Astro UI code for server-first rendering, slots, islands, hydration directives, server islands, actions, scripts, routing, images, styling, view transitions, accessibility, and performance -applyTo: "**/*.{astro,md,mdx,jsx,tsx,ts,js,css,scss}" ---- # Astro Interface Instructions diff --git a/skills/deliver-software/references/base.md b/skills/deliver-software/references/base.md index b4b5d6f..dcc399c 100644 --- a/skills/deliver-software/references/base.md +++ b/skills/deliver-software/references/base.md @@ -1,4 +1,18 @@ -# Shared Copilot Instructions +# Shared engineering defaults + +## Contents + +- What this file is for +- Core engineering stance +- Naming and runtime shape principles +- Boundary honesty +- JavaScript and TypeScript defaults +- Writing and explanation style +- Comments, docs, and TSDoc +- Performance and optimization policy +- Safety and correctness defaults +- Validation mindset +- Default operating mode ## What this file is for diff --git a/skills/deliver-software/references/benchmarks.md b/skills/deliver-software/references/benchmarks.md index 7ca6aa6..d3fb689 100644 --- a/skills/deliver-software/references/benchmarks.md +++ b/skills/deliver-software/references/benchmarks.md @@ -1,7 +1,3 @@ ---- -description: Cross-project benchmarking standards -applyTo: "**/*_bench.{js,ts,jsx,tsx},**/*bench*.{js,ts,jsx,tsx}" ---- # Benchmarking Rules diff --git a/skills/deliver-software/references/changes.md b/skills/deliver-software/references/changes.md index 12815d3..0727be1 100644 --- a/skills/deliver-software/references/changes.md +++ b/skills/deliver-software/references/changes.md @@ -1,7 +1,3 @@ ---- -description: Changelog and release note writing standards for this repo -applyTo: "**" ---- # Changelog writing diff --git a/skills/deliver-software/references/comments.md b/skills/deliver-software/references/comments.md index ead3e2f..ab1f862 100644 --- a/skills/deliver-software/references/comments.md +++ b/skills/deliver-software/references/comments.md @@ -1,7 +1,3 @@ ---- -description: Cross-project TSDoc and code comment writing style -applyTo: "**/*.ts,**/*.tsx" ---- # TSDoc and Comments diff --git a/skills/deliver-software/references/commits.md b/skills/deliver-software/references/commits.md index e6e8bb9..0cddce9 100644 --- a/skills/deliver-software/references/commits.md +++ b/skills/deliver-software/references/commits.md @@ -1,7 +1,3 @@ ---- -description: Commit message writing standards for this repo -applyTo: "**" ---- # Commit messages diff --git a/skills/deliver-software/references/composition.md b/skills/deliver-software/references/composition.md index b341e13..7b25808 100644 --- a/skills/deliver-software/references/composition.md +++ b/skills/deliver-software/references/composition.md @@ -1,10 +1,3 @@ ---- -title: Compose Framework Primitives, Not Renderer-shaped APIs -impact: HIGH -description: preserves composition-first component APIs across React, Solid, and Astro without flattening their different runtime models -tags: composition, jsx, react, solid, astro, slots, children, signals, context, control-flow, design-systems -applyTo: "**/*.md,**/*.{js,ts},**/*.{jsx,tsx},**/*.astro" ---- ## Compose Framework Primitives, Not Renderer-shaped APIs diff --git a/skills/deliver-software/references/delivery.md b/skills/deliver-software/references/delivery.md index 99e8125..eb16a21 100644 --- a/skills/deliver-software/references/delivery.md +++ b/skills/deliver-software/references/delivery.md @@ -1,13 +1,20 @@ ---- -name: "Thorough Delivery" -description: "Use when you need a thorough thermonuclear review, relentless task completion, deliverable audit, refactor completion check, acceptance-criteria validation, or plan-vs-outcome verification. Useful for understanding the real deliverable, locking the deliverable after clarification, coordinating multiple subagents in parallel, preventing premature stop points, enforcing repo instructions, catching partial implementations, spotting leftover compatibility shims, and proving whether a refactor is actually complete." -tools: [execute, read, agent, edit, search, web, 'io.github.upstash/context7/*', specification-website/search, todo] -agents: ["Delivery Planner", "Delivery Validator", "Delivery Verifier", "Delivery Implementer", "Explore"] -argument-hint: "Describe the deliverable, intended end state, current plan, and what must be verified." ---- -You are a delivery auditor and completion enforcer. +Use this as a neutral delivery protocol for the mode selected by the root skill. -Your job is to understand the real requested outcome, make the success criteria explicit, track the work against that target, and verify that the final deliverable actually matches the goal and plan. +## Contents + +- Primary Responsibilities +- Constraints +- Delegation Model +- Stop Conditions +- Deliverable Lock +- Operating Standard +- Approach +- Refactor Completion Checklist +- Verification Rules +- Output Format + +Do not turn a plan into implementation, an implementation into an audit, or a +review into remediation merely because this reference is loaded. You must track two completion states at the same time: 1. deliverable complete @@ -29,13 +36,16 @@ Before changing anything, inspect existing implementations first, prefer read an - Compare the implementation against the stated goal, the plan, and any intermediate promises. - Detect incomplete refactors, stale compatibility layers, dead transitional code, and unverified assumptions. - Delegate focused work to multiple subagents in parallel when that will reduce total time without creating confusion. -- Patch a gap yourself only when it stays within one well-understood surface, requires the smallest local repair, and has one clear verification step. +- Implement the complete authorized change. Delegate independent slices when + useful, but retain ownership of integration and final evidence. - Ask for clarification as early as possible when a missing requirement would change the real target. - Treat progress reports as bookkeeping only; they never replace finishing the work. - Enforce the applicable repo instructions and these workflow rules. ## Constraints -- DO NOT turn into the primary implementation agent when the remaining work spans multiple surfaces, introduces new behavior, or still needs discovery-level planning. +- Remain accountable for the complete implementation. Delegate independent + slices when collaboration is available and useful, but do not make completion + depend on named agents or tools that the current host does not provide. - DO NOT make direct edits until you can name the specific gap, the smallest repair, and the verification that will prove it. - DO NOT stop at "phase 1", "first pass", "initial slice", or any other intermediate milestone when the actual deliverable is larger. - DO NOT mark work complete because a small slice passed; check the whole promised outcome. @@ -63,7 +73,7 @@ Tier 2 is focused subagents for well-scoped questions or parallel inspection. Wh - check which tests cover the promised behavior - find files that still reference transitional APIs or shims - find files that share the same repetitive edit pattern -- check what existing research in `.agents/research/` already answers +- check what an established repository research cache already answers - check whether a maintained package or existing local abstraction already solves the problem Focused subagents may also own validation or verification passes when that is faster, but you must review their evidence rather than trusting a bare success claim. @@ -126,11 +136,13 @@ When the task is a refactor, migration, or architectural move, explicitly check ## Verification Rules - Prefer executable proof over narrative confidence. - Require proof that the real deliverable works when the capability is runnable. -- Treat verification as binary at the end: either the capability is proven, or the task is blocked. +- Distinguish a capability that ran and failed from a capability that could not + be run. - Keep ownership of the final judgment yourself. ## Output Format -Always respond in this shape unless the user asks for something else: +Use only the sections needed for the authorized mode. Reserve the full shape +below for delivery audits and substantial implementations. ### Deliverable State the real requested outcome in plain English. @@ -155,13 +167,8 @@ State the real requested outcome in plain English. - State whether the finished deliverables still match the original goals, requirements, and intent behind the full plan. ### Verdict -Return exactly one verdict: -- blocked -- incomplete - gaps identified -- complete and verified - -Use `blocked` only when progress is impossible without user input or an external dependency. - -Use `incomplete - gaps identified` when work remains, there is no external blocker, and you can name the concrete gap-closing actions. +Use a mode-appropriate verdict: plan complete, review complete, diagnosis +complete, implementation failed verification, implementation complete with +verification blocked, or complete and verified. -If the verdict is not "complete and verified", end with the shortest set of actions required to close the gap. +When work remains, end with the shortest concrete actions required to close it. diff --git a/skills/deliver-software/references/diagrams.md b/skills/deliver-software/references/diagrams.md index 67f6173..dc5d069 100644 --- a/skills/deliver-software/references/diagrams.md +++ b/skills/deliver-software/references/diagrams.md @@ -1,7 +1,3 @@ ---- -description: ASCII diagram guidance for docs, TSDoc, and explanatory comments -applyTo: "**/*.md,**/*.{js,ts},**/*.{jsx,tsx},**/*.astro" ---- # ASCII Diagrams diff --git a/skills/deliver-software/references/docs.md b/skills/deliver-software/references/docs.md index 73931a4..9aaadc0 100644 --- a/skills/deliver-software/references/docs.md +++ b/skills/deliver-software/references/docs.md @@ -1,7 +1,3 @@ ---- -description: "Cross-project Markdown and long-form documentation style" -applyTo: "**/*.md" ---- # Documentation Writing diff --git a/skills/deliver-software/references/implementer.md b/skills/deliver-software/references/implementer.md index 59e77ab..14e546f 100644 --- a/skills/deliver-software/references/implementer.md +++ b/skills/deliver-software/references/implementer.md @@ -1,15 +1,9 @@ ---- -name: "Delivery Implementer" -description: "Use when you need actual code or docs implementation after the deliverable is clear. Good for writing code, refactoring to completion, removing compatibility leftovers, following repo instructions, using workspace tools first, and validating the changed surface before handing off to verification." -tools: [read, search, edit, execute, web, agent, 'io.github.upstash/context7/*'] -argument-hint: "Describe the locked deliverable, the files or surfaces likely involved, and the validation that must pass after edits." ---- You are an implementation specialist for delivery-critical work. Your job is to carry a locked deliverable through concrete code or docs changes without stopping at partial slices, stale compatibility code, or unvalidated edits. When researching or searching, prefer this order unless the task clearly requires something else: -1. `.agents/research/` +1. the repository's established research cache, when one exists 2. applicable instruction files, especially `.github/instructions/` 3. the rest of the codebase @@ -26,9 +20,14 @@ When researching or searching, prefer this order unless the task clearly require ## Approach ### Read / Research -1. Before the first edit, read the parent agent instructions, the repo instructions under `.github/instructions`, and the task-specific instruction files that apply to the touched surfaces. -2. Search `.agents/research/` first, then the relevant instructions, then the broader codebase for existing implementations, related helpers, prior patterns, and reusable modules before creating new code. -3. When external libraries or framework APIs might already solve the problem, check current docs or Context7 before hand-rolling an implementation, then write back reusable findings under `.agents/research/` when they are likely to matter again. Preserve exact API names, deprecations, replacements, versions, and caveats when those details affect implementation choices. +1. Before the first edit, read the parent agent instructions, the repo instructions, and the task-specific instruction files that apply to the touched surfaces. +2. Search an established repository research cache first, then relevant + instructions, code, and dependencies for existing patterns before creating new code. +3. When external libraries or framework APIs might already solve the problem, + check current primary documentation before hand-rolling an implementation. + Record reusable findings only when the repository has an established + research mechanism. Preserve exact API names, deprecations, versions, and + caveats when they affect the implementation. ### Implement 4. If the deliverable cannot be unambiguously restated from the provided input, stop and list the specific clarifying questions needed before any edits are made. diff --git a/skills/deliver-software/references/planner.md b/skills/deliver-software/references/planner.md index 6da2cc9..2003a73 100644 --- a/skills/deliver-software/references/planner.md +++ b/skills/deliver-software/references/planner.md @@ -1,9 +1,3 @@ ---- -name: "Delivery Planner" -description: "Use when you need delivery planning, acceptance criteria, task decomposition, instruction loading guidance, subagent fan-out planning, or verification planning before implementation. Good for locking the deliverable, turning intent into a concrete plan, and deciding which specialized agents should run in parallel." -tools: [read, search, todo, agent, web, 'io.github.upstash/context7/*'] -argument-hint: "Describe the goal, constraints, current state, and what must be proven at the end." ---- You are a planning specialist for delivery-critical work. Your job is to turn an intended outcome into a locked deliverable, explicit acceptance criteria, a task tracker, and a parallel execution plan that other agents can carry out. @@ -11,11 +5,13 @@ Your job is to turn an intended outcome into a locked deliverable, explicit acce Your planning job is not complete until the full plan is covered. Partial planning is not an acceptable stopping point when the larger plan is already in scope. When researching or searching, prefer this order unless the task clearly requires something else: -1. `.agents/research/` when it exists -2. applicable instruction files, especially `.github/instructions/` -3. the rest of the codebase -4. maintained library or framework documentation via Context7 when the plan depends on a library, framework, SDK, API, or CLI -5. broader web search only for gaps that local sources and Context7 do not answer, or for ecosystem comparisons, issue discussions, and version-sensitive operational details +1. the repository's established research cache, when one exists +2. applicable instruction files, including `.github/instructions/` +3. the rest of the codebase including tests, dependencies, examples, and documentation +4. maintained primary library or framework documentation when the plan depends + on a library, framework, SDK, API, or CLI +5. broader web search only for gaps that local and primary sources do not + answer, or for ecosystem comparisons and issue discussions ## Constraints - DO NOT edit files or implement code changes. @@ -32,11 +28,14 @@ If any approach step conflicts with a constraint, the constraint wins. If two ap 1. Extract the requested outcome, constraints, non-goals, and success conditions. 2. Ask for clarification only when the missing information would change the scope, a concrete acceptance criterion, or the verification method. Limit clarification to at most 3 questions. 3. Restate the deliverable in concrete terms and treat it as locked once clear. -4. Search `.agents/research/` first when it exists, then load the applicable repo instructions for the surfaces the task will touch, then search the broader codebase as needed. If `.agents/research/` does not exist or yields no relevant results, state this explicitly in the Research Reuse section before proceeding. +4. Search an established repository research cache first, then applicable + instructions, then dependencies and then the broader codebase. Do not require a bookkeeping section + merely to state that a repository has no cache. 5. Require an early search step for existing local implementations, reusable abstractions, plausible maintained packages, and current maintained documentation before planning new code. -6. Use Context7 as the preferred external documentation source when the plan depends on a library, framework, SDK, API, or CLI. Use broader web search only when Context7 and local sources do not answer the planning question. +6. Use the host's available documentation tools to consult current primary + sources. Never invent a result from a named tool that is unavailable. 7. Build acceptance criteria that describe both what must exist and what must no longer remain. -8. Enumerate the full plan surface that is currently in scope, including every deliverable that must be completed for the plan itself to count as done. +8. Enumerate the full plan surface that is currently in scope, including every deliverable and capability that must be completed for the plan itself to count as done. 9. Build a task tracker that covers implementation, cleanup, validation, verification, final audit, and explicit plan-completion review. 10. Identify which slices can run in parallel and which specialized agents should own them. 11. Define the exact verification plan, including when the deliverable itself must be run. @@ -68,9 +67,10 @@ State the locked outcome in plain English. ### Research Reuse - State what existing research was reused. -- State what external documentation was consulted via Context7. +- State which primary external documentation materially changed the plan. - State what broader web research was consulted and why it was needed. -- State what new research should be written back under `.agents/research/`. +- State what durable research should be retained when the repository has a + mechanism for it. ### Open Questions - List only the questions that would materially change the target. diff --git a/skills/deliver-software/references/pulls.md b/skills/deliver-software/references/pulls.md index 8138f44..82f2c3d 100644 --- a/skills/deliver-software/references/pulls.md +++ b/skills/deliver-software/references/pulls.md @@ -1,7 +1,3 @@ ---- -description: PR title, description, and design note standards for this repo -applyTo: "**" ---- # Pull Requests diff --git a/skills/deliver-software/references/python.md b/skills/deliver-software/references/python.md index a5036a9..8babba7 100644 --- a/skills/deliver-software/references/python.md +++ b/skills/deliver-software/references/python.md @@ -1,7 +1,3 @@ ---- -description: Cross-project Python standards -applyTo: "**/*.py" ---- # Python Rules diff --git a/skills/deliver-software/references/react.md b/skills/deliver-software/references/react.md index 3f12237..4dd5195 100644 --- a/skills/deliver-software/references/react.md +++ b/skills/deliver-software/references/react.md @@ -1,7 +1,3 @@ ---- -description: Write and review React UI code for composition, rendering, state ownership, forms, async behavior, transitions, Suspense, effects, portals, hydration, styling, accessibility, and performance -applyTo: "**/*.{jsx,tsx}" ---- # React Interface Instructions diff --git a/skills/deliver-software/references/refactors.md b/skills/deliver-software/references/refactors.md new file mode 100644 index 0000000..dad696b --- /dev/null +++ b/skills/deliver-software/references/refactors.md @@ -0,0 +1,63 @@ +# Refactors and migrations + +## When to load + +Use this reference for structural replacement, ownership changes, migrations, +cutovers, compatibility windows, and requests whose success requires old paths +to stop being authoritative. + +## 1. Establish the controlling path + +Trace the current entrypoint through registration, configuration, runtime +dispatch, persistence, and downstream consumers. Search symbols and runtime +identifiers, not only filenames. Include generated registries, code generation, +public exports, package entrypoints, dependencies, file & folder names, folder structure, framework discovery, CI, deployment, and +documentation. + +Produce two inventories: + +- required end state: capabilities, public contracts, and supported consumers; +- removal state: obsolete code, exports, flags, configuration, dependencies, + tests, docs, aliases, shims, generated output, and old terminology. + +## 2. Baseline behavior + +Record observable inputs, outputs, errors, side effects, ordering, concurrency, +persistence, performance constraints, permissions, and compatibility promises. +Use existing tests plus characterization tests where behavior matters but is not +specified. + +List intentional behavior changes separately. A structural refactor does not +silently authorize product changes. + +## 3. Design the cutover + +Choose one: + +- atomic replacement when all consumers can move together; +- expand, migrate, verify, contract for data or distributed-system changes; +- an explicitly approved compatibility window with an owner, deadline, removal + condition, and tests for both paths. + +A compatibility layer is not completion unless it is part of the accepted end +state. Generated files must be changed through their generator unless the +repository explicitly treats generated output as authored source. + +## 4. Implement and close + +Change the controlling path, migrate every consumer, regenerate outputs, update +tests and docs, and remove newly obsolete dependencies and configuration. +Search the entire repository for old names and behavior. Confirm that the old +path is unreachable, not merely unused by one test or some older files. + +For monorepos, verify downstream packages and external consumer fixtures. For +data migrations, prove idempotency, mixed-version compatibility, rollback or +forward recovery, and the authority for destructive contraction. + +## 5. Verify + +Run focused validation, repository-wide affected gates, the actual capability, +and at least one clean consumer or clean environment when public contracts +changed. Compare the implemented result with both inventories. Report any +approved compatibility residue explicitly rather than hiding it as cleanup. + diff --git a/skills/deliver-software/references/releases.md b/skills/deliver-software/references/releases.md new file mode 100644 index 0000000..6232b42 --- /dev/null +++ b/skills/deliver-software/references/releases.md @@ -0,0 +1,56 @@ +# Releases + +## Authority and scope + +A release changes external state. Preparing a release, proving readiness, and +publishing are separate actions. Do not publish, push tags, deploy, notify users, +or mutate registries unless the request authorizes that action. + +Identify the product or package, version source of truth, target registries or +environments, workspace release set, supported upgrade paths, and rollback or +forward-fix strategy. + +## Readiness + +Require the repository's real quality gates, a clean or intentionally understood +worktree, current generated artifacts, correct package contents, migration and +compatibility notes, and successful clean-consumer installation. + +For workspaces, verify version and dependency-range consistency across every +released package. Inspect tarballs, bundles, binaries, images, checksums, +signatures, provenance, and SBOMs when those artifacts are part of the release +contract. + +## Mutation preflight + +Before publishing, confirm: + +- authenticated identity and target account; +- package, scope, project, and environment ownership; +- version availability and immutability; +- tag and branch protection; +- secret handling; +- expected messages, charges, or deployment effects; +- recovery from partial multi-target publication. + +Never rewrite an immutable public version or destructively retag a released +commit to hide a partial failure. + +## Publish and verify + +Publish in dependency order where required. Record exact resulting versions, +digests, URLs, and registry states. Install or fetch the released artifact from +its public target into a clean consumer and run a real supported workflow. + +If one target succeeds and another fails, report a partial release. Choose a +forward fix, deprecation, or follow-up version based on registry immutability and +consumer impact. Do not report the release as successful because one target +completed. + +## Post-release + +Verify availability, installation, startup, migrations, telemetry, and +documented examples. Preserve provenance and release evidence. Communicate +breaking changes and recovery steps when user-facing release communication is +in scope. + diff --git a/skills/deliver-software/references/review.md b/skills/deliver-software/references/review.md index a3b6dfb..1ee181d 100644 --- a/skills/deliver-software/references/review.md +++ b/skills/deliver-software/references/review.md @@ -1,7 +1,3 @@ ---- -description: Code review standards for this repo -applyTo: "**" ---- # Code Review diff --git a/skills/deliver-software/references/solid.md b/skills/deliver-software/references/solid.md index ed468b4..935d2c7 100644 --- a/skills/deliver-software/references/solid.md +++ b/skills/deliver-software/references/solid.md @@ -1,7 +1,3 @@ ---- -description: Write and review Solid UI code for fine-grained reactivity, owners, roots, async resources, transitions, Suspense, errors, events, forms, portals, hydration, styling, accessibility, and performance -applyTo: "**/*.{jsx,tsx}" ---- # Solid Interface Instructions diff --git a/skills/deliver-software/references/testing.md b/skills/deliver-software/references/testing.md index 15fb9b1..9d55bbf 100644 --- a/skills/deliver-software/references/testing.md +++ b/skills/deliver-software/references/testing.md @@ -1,7 +1,3 @@ ---- -description: Cross-project test quality standards -applyTo: "**/*_test.{js,ts,jsx,tsx},**/*.test.{js,ts,jsx,tsx}" ---- # Testing Rules diff --git a/skills/deliver-software/references/typescript.md b/skills/deliver-software/references/typescript.md index 315f9ca..5cd328e 100644 --- a/skills/deliver-software/references/typescript.md +++ b/skills/deliver-software/references/typescript.md @@ -1,7 +1,3 @@ ---- -description: Cross-project Deno + TypeScript standards -applyTo: "**/*.ts,**/*.tsx" ---- # TypeScript / Deno Rules diff --git a/skills/deliver-software/references/validator.md b/skills/deliver-software/references/validator.md index 132014b..f6e4d97 100644 --- a/skills/deliver-software/references/validator.md +++ b/skills/deliver-software/references/validator.md @@ -1,30 +1,28 @@ ---- -name: "Delivery Validator" -description: "Use when you need validation of the changed surface: TypeScript issues, lint, targeted tests, instruction compliance, schema-first typing, TSDoc quality, deprecated API detection, or current-library API checks. Good for proving the implementation is internally sound before end-to-end verification." -tools: [execute, read, agent, edit, search, web, 'io.github.upstash/context7/*', specification-website/search] -argument-hint: "Describe the changed surface, the intended contract, and which validations must pass." ---- You are a validation specialist for changed code and docs. Your job is to prove that the changed surface is internally correct, instruction-compliant, and free of obvious technical debt before anyone claims the capability is done. When researching or searching, prefer this order unless the task clearly requires something else: -1. `.agents/research/` -2. applicable instruction files, especially `.github/instructions/` +1. the repository's established research cache, when one exists +2. applicable instruction files, including `.github/instructions/` 3. the rest of the codebase ## Constraints -- DO NOT edit files, except `.agents/research/` when recording reusable findings per step 4. +- DO NOT edit implementation files. Record reusable findings only through an + established repository mechanism. - DO NOT claim the user-facing capability works end to end just because tests or typechecks pass. - DO NOT ignore TypeScript issues, deprecated APIs, stale Zod usage, schema drift, or instruction violations. - ONLY validate the changed surface and the narrow supporting checks that prove it is technically sound. - DO NOT keep clearly separable validation workstreams serialized when focused subagents can check them in parallel. ## Approach -1. Search `.agents/research/` first, then load the applicable repo instructions for the touched surfaces before assessing the change. +1. Search established research and applicable repository instructions before + assessing the changed surface. 2. Inspect the changed code or docs and identify the contract that must hold. 3. Run the narrowest meaningful validation steps, such as targeted typechecks, lint, tests, doc checks, or deprecation checks. -4. Use current documentation when API correctness or deprecation status matters, and write back reusable findings under `.agents/research/` when appropriate. Preserve exact deprecated APIs, replacements, versions, and migration caveats when those details affect validation or remediation. +4. Use current primary documentation when API correctness or deprecation status + matters. Preserve exact replacements, versions, and migration caveats in an + established research mechanism when useful. 5. Check that schemas remain the source of truth and that types are inferred from them where appropriate. 6. When independent validation slices can run in parallel, delegate them to focused subagents and review their evidence rather than trusting a bare pass/fail claim. 7. Report every concrete validation failure with the contract it breaks. @@ -45,6 +43,9 @@ State the files, APIs, or workflows you validated. ### Validation Verdict Return exactly one verdict: - blocked +- failed - validated -Use `blocked` when any required validation check could not be run, when a check fails, or when coverage of the changed surface is insufficient to assert soundness. +Use `failed` when a required check ran and failed. Use `blocked` only when a +required check could not run or the available evidence cannot cover the changed +surface. diff --git a/skills/deliver-software/references/verifier.md b/skills/deliver-software/references/verifier.md index c402663..6af4594 100644 --- a/skills/deliver-software/references/verifier.md +++ b/skills/deliver-software/references/verifier.md @@ -1,9 +1,3 @@ ---- -name: "Delivery Verifier" -description: "Use when you need end-to-end verification of the real deliverable, such as running a CLI, workflow, server, job, migration, generator, or other user-facing capability. Good for proving the actual capability works, not just its tests, lint, or benchmarks." -tools: [read, search, execute, agent] -argument-hint: "Describe the runnable deliverable, the expected user workflow, and what observed behavior must prove success." ---- You are a verification specialist for runnable deliverables. Your job is to prove that the real capability works for a user or operator by running the actual deliverable whenever possible and inspecting the observed result. @@ -43,6 +37,8 @@ State the real deliverable you verified. ### Verification Verdict Return exactly one verdict: - blocked +- failed - verified -Use `blocked` when the capability was not actually proven to work. +Use `failed` when the capability ran and behaved incorrectly. Use `blocked` +when the capability could not be run. diff --git a/skills/deliver-software/references/web.md b/skills/deliver-software/references/web.md index 2baea91..17b6f7a 100644 --- a/skills/deliver-software/references/web.md +++ b/skills/deliver-software/references/web.md @@ -1,7 +1,3 @@ ---- -description: Write and review browser-facing interfaces for accessibility, composition, async states, layout, styling, performance, hydration safety, i18n, and product readiness -applyTo: "**/*.{html,css,scss,js,jsx,ts,tsx,astro,md,mdx}" ---- # Web Interface Guidelines diff --git a/skills/deliver-software/references/workflow.md b/skills/deliver-software/references/workflow.md index 6b559d0..1d0892d 100644 --- a/skills/deliver-software/references/workflow.md +++ b/skills/deliver-software/references/workflow.md @@ -1,7 +1,3 @@ ---- -description: Shared delivery workflow rules for delivery agents, research cache notes, and repo-local automation scripts -applyTo: ".github/agents/*.agent.md,.agents/research/**/*.md,.agents/scripts/**/*.{ts,tsx,js,mjs,mts,md}" ---- # Delivery Workflow @@ -10,13 +6,16 @@ Use these rules for delivery agents, reusable research notes, and repo-local aut ## Search and research order When researching or searching, prefer this order unless the task clearly requires something else: -1. `.agents/research/` -2. applicable instruction files, especially `.github/instructions/` +1. the repository's established research cache, when one exists +2. applicable instruction files, including `.github/instructions/` 3. the rest of the codebase Search local code and reusable notes before inventing new code or repeating external research. -Store a reviewable note under `.agents/research/` whenever you consult external documentation, third-party APIs, or perform non-trivial codebase investigation that produced a non-obvious conclusion. +When the repository already uses `.agents/research/`, store a reviewable note +there only when external research produced a durable, non-obvious conclusion +that future work is likely to reuse. Do not create bookkeeping directories or +research files merely because this reference mentions them. Keep research notes reusable, but do not compress away the details that motivated the search. @@ -55,7 +54,10 @@ Do not default to terminal-driven exploration when workspace tools can do the jo ## Script policy -For repetitive bulk edits or other writing-oriented automation, prefer reviewable Deno + TypeScript scripts under `.agents/scripts/`. +For repetitive bulk edits or other writing-oriented automation, prefer a +reviewable script in the repository's established automation location. Use Deno +and TypeScript when they fit the repository; do not introduce Deno into an +unrelated project solely for a temporary edit. Feel free to use `jsr:` and `npm:` packages when they improve clarity, safety, or reviewability. @@ -95,10 +97,14 @@ For runnable deliverables such as CLIs, jobs, migrations, generators, servers, o Verification is binary at the end: either the capability works and is proven, or the task is blocked. -If the capability cannot be run due to missing environment, credentials, or infrastructure, document the exact blocker in a progress note under `.agents/progress/`, list the verification steps that would be needed, and surface the block explicitly to the requester rather than marking the task done. +If the capability cannot run because of missing environment, credentials, or +infrastructure, report the exact blocker and remaining verification steps. +Write a repository progress note only when the repository already uses that +mechanism or the user requests a durable handoff. Plan completion is also binary at the end: either the plan coverage is complete and reviewed, or the task is blocked. ## Progress notes -You may write progress notes under `.agents/progress/` for long-running work, but progress notes are bookkeeping only. They never replace finishing the work. +You may use the repository's established progress mechanism for long-running +work, but progress notes are bookkeeping only. They never replace completion. diff --git a/skills/deno-software/SKILL.md b/skills/deno-software/SKILL.md index 28aa10e..21312cc 100644 --- a/skills/deno-software/SKILL.md +++ b/skills/deno-software/SKILL.md @@ -20,7 +20,8 @@ This skill owns Deno-specific contracts. When deliver-software is also available, let it own the general delivery lifecycle. Apply this skill as the Deno specialization and do not repeat discovery, planning, cleanup, validation, verification, or reporting stages. When used alone, retain the complete -workflow below so the skill remains independently installable. +workflow by loading +[the standalone fallback](references/16-standalone.md). Deliver working software, not Deno-flavoured snippets. @@ -55,6 +56,7 @@ affect the decision. | Refactors, reviews, debugging | `11-delivery-playbooks.md` | | Final verification | `12-verification.md` | | Ambiguous classification or edge case | `15-decision-cases.md` | +| Lifecycle when deliver-software is unavailable | `16-standalone.md` | Use `references/13-command-reference.md` to confirm command intent. Use current official documentation when a command, option, API, stability status, or @@ -132,337 +134,6 @@ change. configuration, or cross-process data, prefer Zod v4 schemas/codecs as the source of truth and infer TypeScript types. -## End-to-end workflow - -### Stage 1: Resolve the objective - -Translate the request into an outcome that can be verified. - -Capture: - -- user-visible or maintainer-visible outcome; -- behavior that must stay unchanged; -- intentional behavior changes; -- supported runtime, operating systems, CPU architectures, and deployment - targets; -- public APIs and compatibility promises; -- acceptance criteria; -- constraints imposed by connected systems. - -Do not mistake a requested edit for the actual outcome. For example, “replace -npm scripts” may really mean “make local development and CI deterministic under -Deno without breaking external tooling.” - -### Stage 2: Discover the repository - -Run or emulate the audit in `scripts/audit.ts`. At minimum inspect: - -```text -deno.json / deno.jsonc -package.json -npm, pnpm, Yarn, Bun, and Deno lockfiles -workspace declarations -imports and exports -tasks and scripts -entrypoints -source and test layout -CI and release workflows -container and deployment configuration -generated output and ignored paths -``` - -Build a short repository model: - -```text -project mode: -minimum Deno version: -workspace shape: -dependency sources: -entrypoints and public exports: -tasks and CI gates: -permissions: -artifacts and deployment targets: -connected systems: -``` - -### Stage 3: Classify the project mode - -#### Deno-native - -Use when Deno owns execution, tasks, dependency declaration, and distribution. - -Typical source of truth: - -- `deno.json` or `deno.jsonc`; -- `deno.lock`; -- JSR and npm imports declared through Deno configuration; -- Deno tasks and built-in tooling. - -#### package.json-first - -Use when npm ecosystem tooling, package publication, framework conventions, or -existing consumers require package.json to remain authoritative. - -Typical approach: - -- preserve package.json dependencies, scripts, exports, and workspace metadata; -- run existing workflows with Deno where compatible; -- use Deno configuration only for Deno-specific behavior; -- consider `preferPackageJson` only after confirming it fits the current Deno - version and repository workflow. - -#### Hybrid - -Use when both ecosystems have durable responsibilities. - -Document ownership. A common split is: - -```text -package.json - npm publication metadata - dependencies required by Node-oriented tooling - scripts consumed by external tools - exports for npm consumers - -deno.json - Deno workspace membership - Deno tasks and permission sets - lint, fmt, test, coverage, compiler configuration - Deno-native imports and JSR publication metadata -``` - -Do not duplicate dependency declarations without an explicit synchronization -rule. - -### Stage 4: Research uncertain contracts - -Before implementation, verify current official documentation and source when any -of these are material: - -- a feature landed in a recent Deno release; -- a flag or config field may be unstable; -- framework detection, compilation, desktop packaging, or deployment behavior - matters; -- Node compatibility depends on package internals, native addons, subprocesses, - postinstall scripts, or filesystem layout; -- a package's runtime behavior determines architecture; -- a recommendation would replace established tooling. - -Read connected-system documentation and source too. A Deno solution can still -fail because of Vite, Astro, Hono, Drizzle, npm lifecycle scripts, a database -driver, or a deployment target. - -### Stage 5: Design the complete change - -Create an implementation map with objective outcomes, not progress percentages. - -For each deliverable specify: - -- files to add, edit, move, or delete; -- interfaces and data flow; -- behavior preserved and behavior changed; -- configuration and dependency changes; -- migration and rollback concerns; -- tests and fixtures; -- manual or artifact-level validation; -- obsolete paths to remove. - -Revisit the alternatives after research. Compare them again using the same -criteria: correctness, compatibility, security, operability, simplicity, -performance, maintenance cost, and reversibility. - -### Stage 6: Implement with Deno-appropriate defaults - -Unless the repository requires otherwise: - -- use strict TypeScript, ESM, and explicit local file extensions; -- prefer JavaScript-native TypeScript syntax; -- prefer web APIs for portable concerns and Node APIs when compatibility or - ecosystem integration makes them the better contract; -- use JSR for Deno-native packages and `@std/*`, npm for the best available npm - package; -- keep I/O, process, network, environment, FFI, and system access explicit; -- propagate `AbortSignal` through cancellable async work; -- close resources deterministically with `using` / `await using` where supported - and appropriate; -- avoid module-level side effects in libraries; -- keep CLIs thin over reusable application modules; -- keep servers explicit about startup, shutdown, errors, timeouts, and - telemetry; -- make generated outputs reproducible and excluded from lint/format only when - justified. - -### Stage 7: Remove superseded paths - -A refactor or migration is incomplete while an older implementation remains -reachable or documented. - -Search for and remove: - -- old modules and duplicate implementations; -- stale exports and re-export barrels; -- abandoned tasks and scripts; -- unused dependencies and import aliases; -- obsolete compatibility branches; -- outdated docs, examples, fixtures, comments, and environment variables; -- generated artifacts accidentally committed by the old workflow. - -Preserve an old path only when backward compatibility is an explicit -requirement. Mark ownership, deprecation behavior, removal criteria, and tests. - -### Stage 8: Verify in layers - -Start narrow, then expand: - -```bash -deno fmt --check -deno lint -deno check -deno test -``` - -Then run repository gates: - -```bash -deno task check -deno task test -deno task ci -``` - -Use only tasks that actually exist. When no aggregate task exists, run the -underlying commands directly. - -Artifact-level verification is mandatory when producing artifacts: - -- bundle: execute or import the bundle in its intended runtime; -- compiled executable: run the binary and test exit behavior and permissions; -- package: validate exports, docs, publish dry-run, and consumption from a clean - fixture; -- desktop app: build and smoke-test the generated package on supported targets; -- container/deployment: start it with production-like configuration and check - readiness/shutdown. - -### Stage 9: Report exact results - -Report: - -- repository mode and important constraints; -- completed behavior and architecture; -- intentional behavior changes; -- removed obsolete paths; -- commands run and observed results; -- artifact smoke tests; -- unresolved risks and checks blocked by the environment. - -Do not substitute “should work” for verification. - -## Task routers - -### Create a new project - -1. Establish artifact type: script, CLI, library, server, web app, worker, - binary, or desktop app. -2. Pick Deno-native, package.json-first, or hybrid based on consumers and - tooling. -3. Define minimum Deno version and runtime targets. -4. Create the smallest complete structure, including tasks, tests, permissions, - and CI. -5. Add only dependencies required by the design. -6. Verify from a clean checkout or equivalent fixture. - -Use templates in `templates/` as starting points, not unquestioned output. - -### Add a dependency - -1. Confirm the package actually solves the requirement. -2. Check JSR, npm, built-in web APIs, Node APIs, and `@std/*` in that order of - relevance, not ideology. -3. Confirm runtime support, package exports, license, maintenance, transitive - graph, and required permissions. -4. Add through the owning package manager. -5. Inspect `deno list`, lockfile changes, scripts, and native/build - requirements. -6. Add focused integration tests. - -### Migrate Node to Deno - -Treat migration as staged compatibility validation: - -1. preserve the current manifests and lockfile; -2. install with Deno and inspect the resulting graph; -3. run existing scripts unchanged; -4. classify failures: CLI assumptions, Node API gaps, lifecycle scripts, native - addons, module resolution, CJS/ESM, filesystem layout, or unsupported - tooling; -5. fix the smallest incompatibilities first; -6. only move ownership into deno.json when it reduces complexity; -7. keep a reversible checkpoint until production workflows pass. - -Never begin with a broad rewrite. - -### Refactor - -1. map the old design and all consumers; -2. define invariants and intentional changes; -3. introduce the final structure in one coherent change; -4. migrate every caller; -5. remove the old structure and dependencies; -6. search for residue; -7. verify behavioral parity and repository-wide gates. - -Do not leave “temporary” duplicate paths unless the user requested a staged -migration. - -### Review - -Prioritize: - -1. correctness and data loss; -2. security and permission expansion; -3. public API and persisted-data compatibility; -4. cancellation, concurrency, disposal, and shutdown; -5. module resolution and workspace behavior; -6. package and Node compatibility; -7. tests and observability; -8. performance; -9. maintainability; -10. style. - -Every finding must include concrete behavior, affected scenario, complete -correction, and verification. - -### Debug - -1. reproduce with the smallest valid command; -2. record Deno version, OS, architecture, project mode, flags, and environment - assumptions; -3. distinguish resolution, type-check, permission, runtime, network, native - dependency, subprocess, and application failures; -4. use permission traces/audits, `deno info`, `deno list`, logging, and focused - tests as appropriate; -5. fix the cause rather than disabling the guardrail; -6. add a regression test. - -### Publish a library - -1. define the public entrypoints and supported runtimes; -2. avoid hidden global state and broad permissions; -3. validate exported types and documentation; -4. test direct source consumption and packaged consumption; -5. verify semver impact; -6. run a publish dry-run or equivalent package check; -7. test from a clean consumer fixture. - -### Performance work - -1. define the user-visible metric and workload; -2. measure a stable baseline; -3. inspect algorithmic, allocation, I/O, serialization, module-loading, and - permission overhead before micro-optimizing; -4. change one causal factor at a time; -5. benchmark under equivalent conditions; -6. run correctness tests after optimization; -7. report distributions and environment, not only a single best number. ## Output quality contract diff --git a/skills/deno-software/agents/openai.yaml b/skills/deno-software/agents/openai.yaml index 961bced..9616e1f 100644 --- a/skills/deno-software/agents/openai.yaml +++ b/skills/deno-software/agents/openai.yaml @@ -1,18 +1,6 @@ interface: - display_name: deno software - short_description: Deliver complete Deno 2 software. Use for Deno repositories, - deno.json or deno.jsonc, Deno workspaces, JSR packages, Node projects adopting - Deno, CLIs, servers, libraries, scripts, compiled binaries, desktop apps, migrations, - refactors, reviews, debugging, testing, benchmarking, publishing, CI, security, - permissions, dependency management, and architecture decisions. Inspects the repository - first, chooses the correct Deno/package mode, implements the whole change, removes - obsolete paths, and validates behavior with current Deno tooling. - icon_small: assets/icon.svg - icon_large: assets/icon.svg -policy: - products: - - chatgpt - - codex - - api - - atlas - allow_implicit_invocation: true + display_name: "Deno Software" + short_description: "Deliver and verify complete Deno 2 software" + default_prompt: "Use $deno-software to complete and verify this Deno task." + icon_small: "./assets/icon.svg" + icon_large: "./assets/icon.svg" diff --git a/skills/deno-software/references/01-foundations.md b/skills/deno-software/references/01-foundations.md index 7f63c4a..2ee6599 100644 --- a/skills/deno-software/references/01-foundations.md +++ b/skills/deno-software/references/01-foundations.md @@ -1,5 +1,16 @@ # Deno foundations +## Contents + +- Deno is an integrated JavaScript system +- Runtime API selection +- TypeScript +- Side effects and entrypoints +- Cancellation and cleanup +- Errors +- Configuration +- Minimum runtime + ## Deno is an integrated JavaScript system Treat Deno as a runtime, package manager, task runner, formatter, linter, type diff --git a/skills/deno-software/references/02-releases.md b/skills/deno-software/references/02-releases.md index 405a332..54443a3 100644 --- a/skills/deno-software/references/02-releases.md +++ b/skills/deno-software/references/02-releases.md @@ -1,5 +1,19 @@ # Deno 2.0 through 2.9 +## Contents + +- 2.0: architectural baseline +- 2.1: assets, task execution, WebAssembly, LTS +- 2.2: observability, lint plugins, SQLite, tooling depth +- 2.3: production compilation, local packages, project speed +- 2.4: bundle returns, telemetry stabilizes, broader compatibility +- 2.5: permissions in configuration and test lifecycle +- 2.6: `deno x` / `dx`, audit, granular permissions, release-age policy +- 2.7: Temporal, Windows ARM, package overrides +- 2.8: security repair and project-manager maturity +- 2.9: migration, dependency inspection, supply-chain defaults, testing, desktop +- Release-derived rules + The release posts are not a feature dump. Together they describe Deno's direction: make existing JavaScript projects easier to run, consolidate project tooling, improve compatibility without abandoning security, and turn source code diff --git a/skills/deno-software/references/04-packages.md b/skills/deno-software/references/04-packages.md index a302b37..819f093 100644 --- a/skills/deno-software/references/04-packages.md +++ b/skills/deno-software/references/04-packages.md @@ -1,5 +1,22 @@ # Dependencies, manifests, imports, and TypeScript configuration +## Contents + +- First classify the repository +- What `deno.jsonc` owns +- What `package.json` owns +- `preferPackageJson` +- Imports are dependency and resolution aliases +- Scopes +- Exports are the Deno package boundary +- JSR versus npm decision model +- `package.json` dependency guidance +- Node modules modes +- Catalogs +- Lockfiles and package-manager ownership +- Supported TypeScript configuration +- Dependency change validation + This reference exists because Deno can consume both Deno-native and Node/npm project metadata. The files overlap, but they are not interchangeable. Before editing dependencies, decide which file owns each contract. diff --git a/skills/deno-software/references/05-workspaces.md b/skills/deno-software/references/05-workspaces.md index 543620d..f511274 100644 --- a/skills/deno-software/references/05-workspaces.md +++ b/skills/deno-software/references/05-workspaces.md @@ -1,5 +1,23 @@ # Workspaces and monorepos +## Contents + +- Supported member shapes +- Root declaration +- Workspace member identity +- Deno members versus npm members +- Workspace protocol +- Root and member configuration matrix +- Imports and dependency ownership +- Tasks and working directories +- Type checking in workspaces +- Tests, formatting, and linting +- Publishing workspace packages +- Private workspace packages +- Containerization and deployment +- Cross-package refactor procedure +- Workspace audit checklist + Deno workspaces can contain Deno-first packages, Node-first packages, and hybrid packages. Treat a workspace as a resolver and tooling scope, not merely a list of directories. diff --git a/skills/deno-software/references/06-security.md b/skills/deno-software/references/06-security.md index 8dfe447..b3d48eb 100644 --- a/skills/deno-software/references/06-security.md +++ b/skills/deno-software/references/06-security.md @@ -1,5 +1,19 @@ # Security, permission sets, and private dependencies +## Contents + +- Permission categories +- Named permission sets +- Value forms +- Permission sets versus tasks +- Permission design workflow +- Special considerations by category +- Test, benchmark, and compile permissions +- Private npm registries +- Private source modules and repositories +- Supply-chain controls +- Security review checklist + Deno permissions are executable capabilities. They are part of an entrypoint's public operational contract and must be reviewed like network ports, database roles, or filesystem mounts. @@ -101,9 +115,12 @@ Interpretation: - `allow` grants scoped access; - `deny` explicitly blocks matching access and takes precedence over grants; -- `ignore` suppresses permission prompts for matching denied access and is - useful when optional probing is expected; -- an ignored denial still does not grant access. +- `ignore` is supported for read and environment permissions; ignored + operations are silently ignored instead of throwing; +- use it only when the application deliberately treats that missing read or + environment value as optional; +- do not describe `ignore` as a general prompt-suppression control or use it + for permission categories that do not support it. Verify exact current precedence and accepted scope syntax using the Deno config reference when designing a security boundary. diff --git a/skills/deno-software/references/09-libraries.md b/skills/deno-software/references/09-libraries.md index f136b59..ef81ad8 100644 --- a/skills/deno-software/references/09-libraries.md +++ b/skills/deno-software/references/09-libraries.md @@ -1,5 +1,23 @@ # Deno libraries, private packages, JSR, npm, and publication +## Contents + +- Distribution models +- JSR package contract +- Private Deno workspace packages +- Public API design +- JSR versus npm for authors +- Dual-publication contract +- Publication inclusion +- `deno publish` workflow +- Workspace publication +- Interdependent package release +- Private npm publication +- npm package validation +- Semver and breaking changes +- Clean-consumer fixtures +- Publication review checklist + Publishing begins with deciding who consumes the package and through which registry. Do not conflate a workspace package, a private package, a JSR package, and an npm package. @@ -261,7 +279,10 @@ inline in package metadata. Before npm publication: - run the actual build; -- inspect the packed tarball with the package manager's pack command; +- run `deno pack --dry-run` when the Deno project owns the npm package; +- create the tarball with `deno pack`, then inspect its exact contents; +- use the npm package manager's pack command when package.json-first tooling + owns the npm artifact; - install the tarball into a clean Node consumer; - install or consume it with Deno when Deno compatibility is promised; - test all `exports` conditions and subpaths; diff --git a/skills/deno-software/references/13-command-reference.md b/skills/deno-software/references/13-command-reference.md index 837c384..96f5195 100644 --- a/skills/deno-software/references/13-command-reference.md +++ b/skills/deno-software/references/13-command-reference.md @@ -9,6 +9,7 @@ relying on version-sensitive flags. | `deno task` | Run configured Deno or package scripts | | `deno add` / `remove` | Change declared dependencies | | `deno install` | Materialize project dependencies / install executable depending on mode and arguments | +| `deno ci` | Recreate dependencies strictly from a current lockfile for CI | | `deno update` | Update project dependencies | | `deno upgrade` | Upgrade the Deno runtime | | `deno list` | Inspect declared/resolved dependencies | @@ -26,12 +27,17 @@ relying on version-sensitive flags. | `deno compile` | Produce standalone executables | | `deno desktop` | Produce desktop applications; experimental in 2.9 | | `deno publish` | Publish a package to JSR | +| `deno pack` | Create an npm-compatible tarball from a Deno project | | `deno deploy` | Interact with Deno Deploy where applicable | ## Common distinctions - `deno update` changes project dependencies; `deno upgrade` changes the runtime. +- `deno ci` requires a current lockfile, removes existing node_modules, and + installs reproducibly. +- `deno publish` targets JSR; `deno pack` creates an npm-compatible tarball + that still requires clean npm and Deno consumer tests. - `deno list` answers declared/resolved package dependencies; `deno info` is oriented around module graph/cache information. - source execution, bundling, compilation, and desktop packaging produce diff --git a/skills/deno-software/references/16-standalone.md b/skills/deno-software/references/16-standalone.md new file mode 100644 index 0000000..60abc7e --- /dev/null +++ b/skills/deno-software/references/16-standalone.md @@ -0,0 +1,338 @@ +# Standalone delivery fallback + +Load this reference only when deliver-software is unavailable. It preserves the +complete Deno delivery workflow without imposing duplicate lifecycle guidance +when the two skills are composed. + +## End-to-end workflow + +### Stage 1: Resolve the objective + +Translate the request into an outcome that can be verified. + +Capture: + +- user-visible or maintainer-visible outcome; +- behavior that must stay unchanged; +- intentional behavior changes; +- supported runtime, operating systems, CPU architectures, and deployment + targets; +- public APIs and compatibility promises; +- acceptance criteria; +- constraints imposed by connected systems. + +Do not mistake a requested edit for the actual outcome. For example, “replace +npm scripts” may really mean “make local development and CI deterministic under +Deno without breaking external tooling.” + +### Stage 2: Discover the repository + +Run or emulate the audit in `scripts/audit.ts`. At minimum inspect: + +```text +deno.json / deno.jsonc +package.json +npm, pnpm, Yarn, Bun, and Deno lockfiles +workspace declarations +imports and exports +tasks and scripts +entrypoints +source and test layout +CI and release workflows +container and deployment configuration +generated output and ignored paths +``` + +Build a short repository model: + +```text +project mode: +minimum Deno version: +workspace shape: +dependency sources: +entrypoints and public exports: +tasks and CI gates: +permissions: +artifacts and deployment targets: +connected systems: +``` + +### Stage 3: Classify the project mode + +#### Deno-native + +Use when Deno owns execution, tasks, dependency declaration, and distribution. + +Typical source of truth: + +- `deno.json` or `deno.jsonc`; +- `deno.lock`; +- JSR and npm imports declared through Deno configuration; +- Deno tasks and built-in tooling. + +#### package.json-first + +Use when npm ecosystem tooling, package publication, framework conventions, or +existing consumers require package.json to remain authoritative. + +Typical approach: + +- preserve package.json dependencies, scripts, exports, and workspace metadata; +- run existing workflows with Deno where compatible; +- use Deno configuration only for Deno-specific behavior; +- consider `preferPackageJson` only after confirming it fits the current Deno + version and repository workflow. + +#### Hybrid + +Use when both ecosystems have durable responsibilities. + +Document ownership. A common split is: + +```text +package.json + npm publication metadata + dependencies required by Node-oriented tooling + scripts consumed by external tools + exports for npm consumers + +deno.json + Deno workspace membership + Deno tasks and permission sets + lint, fmt, test, coverage, compiler configuration + Deno-native imports and JSR publication metadata +``` + +Do not duplicate dependency declarations without an explicit synchronization +rule. + +### Stage 4: Research uncertain contracts + +Before implementation, verify current official documentation and source when any +of these are material: + +- a feature landed in a recent Deno release; +- a flag or config field may be unstable; +- framework detection, compilation, desktop packaging, or deployment behavior + matters; +- Node compatibility depends on package internals, native addons, subprocesses, + postinstall scripts, or filesystem layout; +- a package's runtime behavior determines architecture; +- a recommendation would replace established tooling. + +Read connected-system documentation and source too. A Deno solution can still +fail because of Vite, Astro, Hono, Drizzle, npm lifecycle scripts, a database +driver, or a deployment target. + +### Stage 5: Design the complete change + +Create an implementation map with objective outcomes, not progress percentages. + +For each deliverable specify: + +- files to add, edit, move, or delete; +- interfaces and data flow; +- behavior preserved and behavior changed; +- configuration and dependency changes; +- migration and rollback concerns; +- tests and fixtures; +- manual or artifact-level validation; +- obsolete paths to remove. + +Revisit the alternatives after research. Compare them again using the same +criteria: correctness, compatibility, security, operability, simplicity, +performance, maintenance cost, and reversibility. + +### Stage 6: Implement with Deno-appropriate defaults + +Unless the repository requires otherwise: + +- use strict TypeScript, ESM, and explicit local file extensions; +- prefer JavaScript-native TypeScript syntax; +- prefer web APIs for portable concerns and Node APIs when compatibility or + ecosystem integration makes them the better contract; +- use JSR for Deno-native packages and `@std/*`, npm for the best available npm + package; +- keep I/O, process, network, environment, FFI, and system access explicit; +- propagate `AbortSignal` through cancellable async work; +- close resources deterministically with `using` / `await using` where supported + and appropriate; +- avoid module-level side effects in libraries; +- keep CLIs thin over reusable application modules; +- keep servers explicit about startup, shutdown, errors, timeouts, and + telemetry; +- make generated outputs reproducible and excluded from lint/format only when + justified. + +### Stage 7: Remove superseded paths + +A refactor or migration is incomplete while an older implementation remains +reachable or documented. + +Search for and remove: + +- old modules and duplicate implementations; +- stale exports and re-export barrels; +- abandoned tasks and scripts; +- unused dependencies and import aliases; +- obsolete compatibility branches; +- outdated docs, examples, fixtures, comments, and environment variables; +- generated artifacts accidentally committed by the old workflow. + +Preserve an old path only when backward compatibility is an explicit +requirement. Mark ownership, deprecation behavior, removal criteria, and tests. + +### Stage 8: Verify in layers + +Start narrow, then expand: + +```bash +deno fmt --check +deno lint +deno check +deno test +``` + +Then run repository gates: + +```bash +deno task check +deno task test +deno task ci +``` + +Use only tasks that actually exist. When no aggregate task exists, run the +underlying commands directly. + +Artifact-level verification is mandatory when producing artifacts: + +- bundle: execute or import the bundle in its intended runtime; +- compiled executable: run the binary and test exit behavior and permissions; +- package: validate exports, docs, publish dry-run, and consumption from a clean + fixture; +- desktop app: build and smoke-test the generated package on supported targets; +- container/deployment: start it with production-like configuration and check + readiness/shutdown. + +### Stage 9: Report exact results + +Report: + +- repository mode and important constraints; +- completed behavior and architecture; +- intentional behavior changes; +- removed obsolete paths; +- commands run and observed results; +- artifact smoke tests; +- unresolved risks and checks blocked by the environment. + +Do not substitute “should work” for verification. + +## Task routers + +### Create a new project + +1. Establish artifact type: script, CLI, library, server, web app, worker, + binary, or desktop app. +2. Pick Deno-native, package.json-first, or hybrid based on consumers and + tooling. +3. Define minimum Deno version and runtime targets. +4. Create the smallest complete structure, including tasks, tests, permissions, + and CI. +5. Add only dependencies required by the design. +6. Verify from a clean checkout or equivalent fixture. + +Use templates in `templates/` as starting points, not unquestioned output. + +### Add a dependency + +1. Confirm the package actually solves the requirement. +2. Check JSR, npm, built-in web APIs, Node APIs, and `@std/*` in that order of + relevance, not ideology. +3. Confirm runtime support, package exports, license, maintenance, transitive + graph, and required permissions. +4. Add through the owning package manager. +5. Inspect `deno list`, lockfile changes, scripts, and native/build + requirements. +6. Add focused integration tests. + +### Migrate Node to Deno + +Treat migration as staged compatibility validation: + +1. preserve the current manifests and lockfile; +2. install with Deno and inspect the resulting graph; +3. run existing scripts unchanged; +4. classify failures: CLI assumptions, Node API gaps, lifecycle scripts, native + addons, module resolution, CJS/ESM, filesystem layout, or unsupported + tooling; +5. fix the smallest incompatibilities first; +6. only move ownership into deno.json when it reduces complexity; +7. keep a reversible checkpoint until production workflows pass. + +Never begin with a broad rewrite. + +### Refactor + +1. map the old design and all consumers; +2. define invariants and intentional changes; +3. introduce the final structure in one coherent change; +4. migrate every caller; +5. remove the old structure and dependencies; +6. search for residue; +7. verify behavioral parity and repository-wide gates. + +Do not leave “temporary” duplicate paths unless the user requested a staged +migration. + +### Review + +Prioritize: + +1. correctness and data loss; +2. security and permission expansion; +3. public API and persisted-data compatibility; +4. cancellation, concurrency, disposal, and shutdown; +5. module resolution and workspace behavior; +6. package and Node compatibility; +7. tests and observability; +8. performance; +9. maintainability; +10. style. + +Every finding must include concrete behavior, affected scenario, complete +correction, and verification. + +### Debug + +1. reproduce with the smallest valid command; +2. record Deno version, OS, architecture, project mode, flags, and environment + assumptions; +3. distinguish resolution, type-check, permission, runtime, network, native + dependency, subprocess, and application failures; +4. use permission traces/audits, `deno info`, `deno list`, logging, and focused + tests as appropriate; +5. fix the cause rather than disabling the guardrail; +6. add a regression test. + +### Publish a library + +1. define the public entrypoints and supported runtimes; +2. avoid hidden global state and broad permissions; +3. validate exported types and documentation; +4. test direct source consumption and packaged consumption; +5. verify semver impact; +6. run a publish dry-run or equivalent package check; +7. test from a clean consumer fixture. + +### Performance work + +1. define the user-visible metric and workload; +2. measure a stable baseline; +3. inspect algorithmic, allocation, I/O, serialization, module-loading, and + permission overhead before micro-optimizing; +4. change one causal factor at a time; +5. benchmark under equivalent conditions; +6. run correctness tests after optimization; +7. report distributions and environment, not only a single best number. + diff --git a/skills/deno-software/scripts/audit.ts b/skills/deno-software/scripts/audit.ts index 7b5e8ad..f27af28 100644 --- a/skills/deno-software/scripts/audit.ts +++ b/skills/deno-software/scripts/audit.ts @@ -1,3 +1,5 @@ +import { z } from "zod"; + /** * Performs a conservative, read-only audit of a Deno or hybrid repository. * @@ -6,18 +8,20 @@ * are prompts for review, not guaranteed defects. */ -interface AuditFinding { - readonly level: "info" | "warning"; - readonly code: string; - readonly message: string; -} +const AuditFindingSchema = z.object({ + level: z.enum(["info", "warning"]), + code: z.string(), + message: z.string(), +}); +type AuditFinding = z.infer; -interface AuditReport { - readonly root: string; - readonly mode: "deno-native" | "package-json-first" | "hybrid" | "unknown"; - readonly files: readonly string[]; - readonly findings: readonly AuditFinding[]; -} +const AuditReportSchema = z.object({ + root: z.string(), + manifestShape: z.enum(["deno-only", "package-only", "both", "none"]), + files: z.array(z.string()), + findings: z.array(AuditFindingSchema), +}); +type AuditReport = z.infer; const decoder = new TextDecoder(); @@ -58,14 +62,14 @@ async function walk(root: string, depth = 0): Promise { return output; } -function detectMode( +function detectManifestShape( hasDeno: boolean, hasPackage: boolean, -): AuditReport["mode"] { - if (hasDeno && hasPackage) return "hybrid"; - if (hasDeno) return "deno-native"; - if (hasPackage) return "package-json-first"; - return "unknown"; +): AuditReport["manifestShape"] { + if (hasDeno && hasPackage) return "both"; + if (hasDeno) return "deno-only"; + if (hasPackage) return "package-only"; + return "none"; } async function audit(root: string): Promise { @@ -133,15 +137,15 @@ async function audit(root: string): Promise { }); } - return { + return AuditReportSchema.parse({ root, - mode: detectMode(hasDeno, hasPackage), + manifestShape: detectManifestShape(hasDeno, hasPackage), files: files.filter((file) => /(?:deno\.jsonc?|package\.json|lock|_test\.|\.test\.|\.spec\.|\.github\/workflows)/ .test(file) ), findings, - }; + }); } if (import.meta.main) { diff --git a/skills/deno-software/scripts/validate.ts b/skills/deno-software/scripts/validate.ts index 11ac13e..6ee4cfe 100644 --- a/skills/deno-software/scripts/validate.ts +++ b/skills/deno-software/scripts/validate.ts @@ -3,12 +3,12 @@ const root = new URL("../", import.meta.url); const required = [ "SKILL.md", - "README.md", "references/01-foundations.md", "references/02-releases.md", "references/12-verification.md", "scripts/audit.ts", "evals/cases.json", + "agents/openai.yaml", ]; for (const relative of required) { @@ -20,6 +20,11 @@ if (!skill.startsWith("---\nname: deno-software\n")) { throw new Error("SKILL.md frontmatter is missing or malformed"); } +const name = skill.match(/^name:\s*(.+)$/m)?.[1]?.trim(); +if (name !== "deno-software") { + throw new Error("SKILL.md name must match the deno-software directory"); +} + for ( const match of skill.matchAll( /`((?:references|scripts|templates|examples|evals)\/[^`]+)`/g, @@ -33,4 +38,19 @@ for ( } } +for (const match of skill.matchAll(/\[[^\]]+\]\(([^)#]+)(?:#[^)]+)?\)/g)) { + const path = match[1]; + if (/^https?:/.test(path)) continue; + try { + await Deno.stat(new URL(path, root)); + } catch (cause) { + throw new Error(`Missing Markdown-linked path: ${path}`, { cause }); + } +} + +const description = skill.match(/^description:\s*(.+)$/m)?.[1]?.trim(); +if (!description || description.length > 1024) { + throw new Error("SKILL.md description must contain 1 to 1024 characters"); +} + console.log("deno-software skill structure is valid"); diff --git a/skills/deno-software/templates/ci.yml b/skills/deno-software/templates/ci.yml index 566b2e4..d2477ee 100644 --- a/skills/deno-software/templates/ci.yml +++ b/skills/deno-software/templates/ci.yml @@ -12,7 +12,7 @@ jobs: - uses: denoland/setup-deno@v2 with: deno-version: v2.9.0 - - run: deno install --frozen + - run: deno ci - run: deno fmt --check - run: deno lint - run: deno check src/mod.ts -- 2.51.2