Wave 0b·B — .agents/docs + skills cluster

.agents/docs/README.md

@@ -0,0 +1,196 @@
+# NetScript — Agent Docs
+
+Agent-facing documentation for the NetScript repo. These docs explain the system architecture,
+conventions, and operating procedures that an AI agent needs to work effectively in this codebase.
+
+> **Complement, don't duplicate.** The public-facing docs live in `docs/` (architecture doctrine,
+> standards, public-surface patterns). The agent docs here focus on _how to operate_ the codebase —
+> harness workflows, skill routing, package conventions, and gotchas.
+
+---
+
+## Start here
+
+| Doc                                             | Why you'd read this                                         |
+| ----------------------------------------------- | ----------------------------------------------------------- |
+| [Architecture Overview](#architecture-overview) | High-level design, layering, and how the repo is organized. |
+| [Getting Started](#getting-started)             | Build, test, and validation commands.                       |
+| [Skill Router](#skill-router)                   | Which skill to load for which task.                         |
+
+---
+
+## Architecture Overview
+
+NetScript is a modular framework for building Deno/TypeScript services with a doctrine-enforced
+package structure. It is organized around three concerns:
+
+1. **Framework core** — The harness, doctrine, and archetypes that govern how packages are shaped.
+2. **Packages** — The 23 publishable units (`packages/*`) that provide runtime capabilities (KV,
+   queues, sagas, workers, triggers, CLI, etc.).
+3. **Plugins** — The 4 first-party plugins (`plugins/*`) that extend the framework.
+
+### Guiding Principles
+
+- **Doctrine-first** — Every package follows the 10-file architecture doctrine. New decisions become
+  ADRs; existing doctrine is append-only.
+- **Archetype-driven** — Each package selects one of six archetypes (Small Contract, Integration,
+  Runtime/Behavior, DSL/Builder, Plugin, CLI/Tooling). The archetype determines the minimum viable
+  shape and gate set.
+- **Composition over inheritance** — Base classes are stub-only contracts; concrete classes
+  delegate. Extension axes are named before abstraction.
+- **Thin core, fat targets** — The harness and doctrine are the stable core; packages carry their
+  own dialect-specific logic.
+- **Feedback before execution** — The harness Plan-Gate catches planning errors before code is
+  written; fitness gates catch structural violations before merge.
+
+### Repo Layout
+
+```
+packages/
+  shared/                # Foundation types, schemas, invariants
+  contracts/             # Contract primitives, schemas, CRUD/query/transform helpers
+  config/                # Typed project configuration schemas and loaders
+  runtime-config/        # Runtime configuration resolution
+  logger/                # Logging
+  telemetry/             # OpenTelemetry instrumentation
+  aspire/                # .NET Aspire integration
+  kv/                    # Key-value storage
+  database/              # Database ports and adapters
+  prisma-adapter-mysql/  # Prisma MySQL adapter
+  queue/                 # Message queuing
+  cron/                  # Job scheduling
+  plugin/                # Plugin runner and authoring SDK
+  plugin-streams-core/   # Streams plugin core
+  plugin-workers-core/   # Workers plugin core
+  plugin-sagas-core/     # Sagas plugin core
+  plugin-triggers-core/  # Triggers plugin core
+  watchers/              # Resource watchers
+  sdk/                   # SDK surface
+  service/               # Service runtime
+  fresh/                 # Fresh 2.x framework integration
+  fresh-ui/              # Fresh UI components
+  cli/                   # Command-line interface
+plugins/
+  streams/               # Streams plugin
+  workers/               # Workers plugin
+  sagas/                 # Sagas plugin
+  triggers/              # Triggers plugin
+docs/
+  architecture/    # Public-facing architecture docs and doctrine
+.agents/
+  skills/          # Agent skills (doctrine, harness, JSR audit, etc.)
+  rules/           # .mdc rule files
+  docs/            # This directory — agent-facing docs
+.llm/
+  harness/         # Harness v2 (workflows, gates, evaluator protocols)
+```
+
+### Subsystems Index
+
+| Subsystem         | Path                       | What it covers                             |
+| ----------------- | -------------------------- | ------------------------------------------ |
+| Foundation        | `packages/shared/`         | Foundation types, schemas, invariants      |
+| Contracts         | `packages/contracts/`      | Contract primitives, CRUD/query/transform  |
+| Configuration     | `packages/config/`         | Schema-driven config with validation       |
+| Runtime config    | `packages/runtime-config/` | Runtime configuration resolution           |
+| Logging           | `packages/logger/`         | Structured logging                         |
+| Telemetry         | `packages/telemetry/`      | OpenTelemetry instrumentation              |
+| KV store          | `packages/kv/`             | Key-value storage with TTL and namespacing |
+| Database          | `packages/database/`       | Database ports and adapters                |
+| Queuing           | `packages/queue/`          | Message queue abstractions                 |
+| Scheduling        | `packages/cron/`           | Cron expression parsing and job scheduling |
+| Plugin SDK        | `packages/plugin/`         | Plugin runner and authoring SDK            |
+| Plugin cores      | `packages/plugin-*-core/`  | Streams, workers, sagas, triggers cores    |
+| CLI               | `packages/cli/`            | Command-line scaffolding and tooling       |
+| Fresh integration | `packages/fresh/`          | Fresh 2.x framework bindings               |
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- [Deno](https://deno.land/) v2.x
+- Git
+
+### Build and test
+
+```bash
+# Format and lint
+deno fmt
+deno lint
+
+# Type check all packages and plugins
+deno task check
+
+# Run tests
+deno task test
+
+# Run CLI E2E tests (expensive — run before merge)
+deno task e2e:cli
+```
+
+### Working with the harness
+
+```bash
+# Start a harnessed run
+# (say "use harness" to the agent, or load .agents/skills/netscript-harness/SKILL.md)
+```
+
+The harness uses an 8-phase model: Bootstrap → Research → Plan & Design → **Plan-Gate** → Implement
+→ Gate → Evaluate → Close.
+
+See `.llm/harness/workflow/run-loop.md` for the full specification.
+
+---
+
+## Skill Router
+
+When a prompt is vague, route it to the narrowest skill:
+
+| Task                                   | Skill                 |
+| -------------------------------------- | --------------------- |
+| `packages/` or `plugins/` architecture | `netscript-doctrine`  |
+| `use harness` or run orchestration     | `netscript-harness`   |
+| JSR readiness or publish audit         | `jsr-audit`           |
+| Fresh/Deno frontend                    | `deno-fresh`          |
+| Anything else                          | Ask for clarification |
+
+See `.agents/skills/README.md` for the full scope table.
+
+---
+
+## Working with AI Agents
+
+| Doc                                                              | Why you'd read this                                   |
+| ---------------------------------------------------------------- | ----------------------------------------------------- |
+| [Harness Activation](../../.llm/harness/workflow/activation.md)  | Bootstrap reading list and mandatory artifacts.       |
+| [Run Loop](../../.llm/harness/workflow/run-loop.md)              | The 8-phase model with Plan-Gate and dual evaluators. |
+| [Plan-Gate](../../.llm/harness/gates/plan-gate.md)               | Checklist for the PLAN-EVAL pass.                     |
+| [Supervisor Workflow](../../.llm/harness/workflow/supervisor.md) | Multi-group supervisor runs.                          |
+| [Skill Authoring](../skills/DEVELOPING.md)                       | How to write a new skill.                             |
+
+---
+
+## Reference
+
+| Doc                                                                           | Why you'd read this                                                                  |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| [Architecture Doctrine](../../docs/architecture/doctrine/)                    | The 10-file specification (A1–A14, archetypes, AP-1..AP-20, F-1..F-18).              |
+| [Public Surface Patterns](../../docs/architecture/PUBLIC-SURFACE-PATTERNS.md) | How to design exports, `mod.ts`, and READMEs for JSR.                                |
+| [Agent Rules](../rules/)                                                      | `.mdc` rule files for CLI, architecture, public surface, JSR, platform, and harness. |
+| [Archetype Gate Matrix](../../.llm/harness/gates/archetype-gate-matrix.md)    | Required gates per archetype.                                                        |
+| [Architecture Debt](../../.llm/harness/debt/arch-debt.md)                     | Persistent debt entries with owners and closing gates.                               |
+
+---
+
+## OSS Posture
+
+| Doc          | Why you'd read this                                        |
+| ------------ | ---------------------------------------------------------- |
+| Governance   | _(stub)_ Decision-making and contribution policies.        |
+| Supply Chain | _(stub)_ License validation, provenance, dependency audit. |
+| Versioning   | _(stub)_ Release procedure and supported versions.         |
+| Telemetry    | _(stub)_ What the CLI collects and how to opt out.         |
+
+> OSS posture docs are stubs. Expand only when real policy is ratified.

.agents/skills/DEVELOPING.md

@@ -0,0 +1,129 @@
+# Developing NetScript Skills
+
+Authoring rules, cluster conventions, and the worked example for concepts-over-procedures. Read this
+before adding or rewriting a `SKILL.md`.
+
+---
+
+## Skill shape
+
+Every `SKILL.md` in this cluster follows the same sections, in order:
+
+### 1. Preamble (YAML frontmatter)
+
+```yaml
+---
+name: <skill-name>
+description: >
+  One-line description that an agent runtime matches against the user's prompt.
+---
+```
+
+- `name` — kebab-case, matches the folder name.
+- `description` — the matching string for agent runtimes. Be specific; vague descriptions cause
+  routing errors.
+
+### 2. Canonical mental-model headline
+
+One sentence that captures the skill's core idea. This is the first paragraph after the frontmatter.
+It should be memorable enough that an agent can recall it when the skill is not loaded.
+
+Example:
+
+> This skill is a navigator. The doctrine remains authoritative; read the relevant doctrine file
+> before changing or evaluating package/plugin code.
+
+### 3. When to Use
+
+Bullet list of specific triggers. Be concrete:
+
+- Good: "Creating a new Fresh web application"
+- Bad: "Working with code"
+
+### 4. When Not to Use
+
+Boundaries prevent routing errors. State what this skill does not cover and which skill (if any)
+does.
+
+Example:
+
+> For app, service, frontend, or infrastructure work, use this skill only when the work changes or
+> evaluates package/plugin surfaces.
+
+### 5. Key Concepts
+
+The vocabulary an agent needs to reason about this domain. Use tables for quick reference.
+
+### 6. Workflow
+
+The typical sequence of actions when this skill is active. Numbered list, not prose narrative.
+
+### 7. Common Pitfalls
+
+Mistakes LLMs commonly make in this domain. Each pitfall names the mistake, why it happens, and how
+to avoid it.
+
+### 8. What NetScript doesn't do yet
+
+**Status: draft — pending user approval before becoming mandatory.**
+
+This section names features the framework does not implement, along with:
+
+- the workaround available today,
+- the skill or doc to route the request to,
+- a note that the feature is tracked (or not yet tracked).
+
+This prevents agents from confabulating plausible-looking API calls against something that does not
+exist.
+
+Example shape:
+
+```markdown
+## What NetScript doesn't do yet
+
+- **Feature X** — Not implemented. Workaround: use Y. Track via a GitHub issue (or
+  `.llm/harness/debt/arch-debt.md` for framework-level gaps).
+```
+
+### 9. Reference Files
+
+Canonical files this skill points to. Use a table with "Load when" column.
+
+### 10. Checklist
+
+Quick verification steps before handing off. 3–5 items.
+
+---
+
+## Router convention
+
+One skill in the cluster acts as the router. Currently `netscript-harness` catches `use harness`
+prompts, and `netscript-doctrine` catches package/plugin work. If you add a skill that overlaps with
+an existing one, update the router skill's description or add an explicit routing table.
+
+---
+
+## Versioning in lockstep
+
+Skills ship with the repo, not as a separate package. The skill surface must match the code surface.
+When the codebase changes:
+
+1. Update the affected skill's content.
+2. Update the skills cluster `README.md` scope table if the skill's scope changed.
+3. Run `deno fmt` on the skill file.
+
+Do not version skills independently of the repo.
+
+---
+
+## Review checklist for new skills
+
+Before committing a new skill:
+
+- [ ] Follows the 10-section shape above.
+- [ ] Has a specific, non-vague `description` in YAML frontmatter.
+- [ ] Includes "When Not to Use" boundaries.
+- [ ] All referenced files exist in the repo.
+- [ ] `deno fmt` clean.
+- [ ] Added to `.agents/skills/README.md` scope table.
+- [ ] Router skill updated if needed.

.agents/skills/README.md

@@ -0,0 +1,69 @@
+# NetScript Skills
+
+Agent skills for the NetScript repo. A small set of `SKILL.md` files that teach an LLM agent how to
+operate this codebase end-to-end without re-deriving the API from documentation each time.
+
+> **Install the version that matches your NetScript version.** Skills ship in lockstep with the
+> codebase. Keep the git ref aligned with the branch you are working on.
+
+---
+
+## What's in the box
+
+| Skill                 | Scope                                                                                           | Status |
+| --------------------- | ----------------------------------------------------------------------------------------------- | ------ |
+| `netscript-doctrine`  | **CORE** — Navigate the architecture doctrine for `packages/` and `plugins/`.                   | active |
+| `netscript-harness`   | **CORE** — Orchestrate harness-mode runs (8-phase model, Plan-Gate, dual evaluators).           | active |
+| `jsr-audit`           | **CORE** — Audit packages for JSR readiness. Required Plan-Gate input for package/plugin waves. | active |
+| `deno-fresh`          | Frontend development with Fresh 2.x, Preact, and Tailwind CSS in Deno.                          | active |
+| `netscript-standards` | **LEGACY** — Superseded by `netscript-doctrine`. Do not use for new work.                       | legacy |
+
+> **Not yet in this repo.** These skills exist in the broader NetScript toolkit but are not present
+> in this repository yet — do not assume their guidance is loadable here: `deno-expert`,
+> `frontend-design`, `ux-patterns`, `tailwind`, `web-design`, `aspire`, `rtk`.
+
+---
+
+## Router
+
+If a prompt is vague, route it to the narrowest skill that fits:
+
+- `packages/` or `plugins/` work → `netscript-doctrine`
+- `use harness` or run orchestration → `netscript-harness`
+- JSR readiness or publish audit → `jsr-audit`
+- Fresh/Deno frontend → `deno-fresh`
+- Anything else → ask for clarification rather than guess
+
+---
+
+## Skill shape
+
+Every skill follows the same shape:
+
+1. **Preamble** — YAML frontmatter with `name`, `description`, and optional metadata.
+2. **Canonical mental-model headline** — One sentence that captures the skill's core idea.
+3. **When to Use** — Specific triggers that activate this skill.
+4. **When Not to Use** — Boundaries; what this skill does not cover.
+5. **Key Concepts** — The vocabulary an agent needs to reason about this domain.
+6. **Workflow** — The typical sequence of actions when this skill is active.
+7. **Common Pitfalls** — Mistakes LLMs commonly make in this domain.
+8. **What NetScript doesn't do yet** — _(draft — pending user approval)_ Features the framework does
+   not implement, with workarounds.
+9. **Reference Files** — Canonical files this skill points to.
+10. **Checklist** — Quick verification steps before handing off.
+
+See [`DEVELOPING.md`](DEVELOPING.md) for the full authoring guide.
+
+---
+
+## Versioning
+
+Skills are versioned in lockstep with the NetScript codebase. The skill surface (commands it
+references, exit codes it expects, capability claims it makes) tracks the repo's current branch. Pin
+per-branch to keep skills, harness, and doctrine coherent.
+
+---
+
+## Contributing
+
+Read [`DEVELOPING.md`](DEVELOPING.md) before adding or rewriting a `SKILL.md`.