@deftai/directive-content 0.55.0

package/conventions/rule-ownership.json

@@ -0,0 +1,382 @@
+{
+  "version": 1,
+  "description": "Rule Ownership Map (ROM): structural source of truth mapping each load-bearing framework rule to its owning file and section. Replaces the descriptive prose section removed from REFERENCES.md by the PR #401 trim. Every entry is enforced by scripts/rule_ownership_lint.py via tasks/verify.yml -> task check; drift between this map and the owner files fails CI. Authority values follow RFC2119 (MUST/SHOULD/MUST_NOT/SHOULD_NOT/AXIOM) with the additional 'lesson' value reserved for rules whose source of truth is a meta/lessons.md entry. See vBRIEF: vbrief/proposed/2026-04-27-635-rule-ownership-map-data-file-and-lint.vbrief.json. Refs #635 (epic), #642 (workflow umbrella), #634 (determinism-tier ladder T5/T6).",
+  "rules": [
+    {
+      "id": "coding-standards-modularity",
+      "text": "One responsibility per file/module",
+      "owner_file": "content/coding/coding.md",
+      "owner_section": "## Code Design",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "coding-standards-contract-first",
+      "text": "Define interfaces/types/protocols before implementation",
+      "owner_file": "content/coding/coding.md",
+      "owner_section": "## Code Design",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "coding-standards-error-handling-no-hide",
+      "text": "Empty catch/except/recover blocks that swallow errors silently",
+      "owner_file": "content/coding/coding.md",
+      "owner_section": "## Code Design",
+      "authority": "MUST_NOT",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "coding-standards-quality-checks",
+      "text": "Run all relevant checks (lint, fmt, quality, build, test) before submitting changes",
+      "owner_file": "content/coding/coding.md",
+      "owner_section": "## Quality Standards",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "codebase-hygiene-dead-code",
+      "text": "Commented-out code blocks committed to version control",
+      "owner_file": "content/coding/hygiene.md",
+      "owner_section": "## Dead Code Removal",
+      "authority": "MUST_NOT",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "codebase-hygiene-circular-dependencies",
+      "text": "Circular imports between modules/packages",
+      "owner_file": "content/coding/hygiene.md",
+      "owner_section": "## Circular Dependencies",
+      "authority": "MUST_NOT",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "codebase-hygiene-error-hiding",
+      "text": "Empty catch/except/recover blocks that swallow errors silently",
+      "owner_file": "content/coding/hygiene.md",
+      "owner_section": "## Error Handling: No Hiding",
+      "authority": "MUST_NOT",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "codebase-hygiene-legacy-deprecated",
+      "text": "Parallel implementations: old approach and new approach coexisting",
+      "owner_file": "content/coding/hygiene.md",
+      "owner_section": "## Legacy and Deprecated Code",
+      "authority": "MUST_NOT",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "codebase-hygiene-dry",
+      "text": "Extract shared abstractions when logic is duplicated across 2+ call sites",
+      "owner_file": "content/coding/hygiene.md",
+      "owner_section": "## DRY: Don't Repeat Yourself",
+      "authority": "SHOULD",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "codebase-hygiene-comments-signal-vs-noise",
+      "text": "Comments should explain **why**, not **what**",
+      "owner_file": "content/coding/hygiene.md",
+      "owner_section": "## Comments: Signal vs. Noise",
+      "authority": "SHOULD",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "testing-universal-coverage",
+      "text": "Achieve \u226585% coverage (overall + per-module/package/file)",
+      "owner_file": "content/coding/testing.md",
+      "owner_section": "## Universal Requirements",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "testing-test-first-development",
+      "text": "Implementation is INCOMPLETE until tests written AND `task test:coverage` passes",
+      "owner_file": "content/coding/testing.md",
+      "owner_section": "## Test-First Development",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "build-output-artifact-verification",
+      "text": "After running a custom build script, verify expected output files exist and are non-empty",
+      "owner_file": "content/coding/build-output.md",
+      "owner_section": "## Artifact Verification",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "toolchain-pre-implementation-gate",
+      "text": "Before beginning implementation, verify all required toolchain components are installed and functional",
+      "owner_file": "content/coding/toolchain.md",
+      "owner_section": "## Pre-Implementation Gate",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "verification-stub-detection",
+      "text": "Scan for incomplete implementations before marking done",
+      "owner_file": "content/verification/verification.md",
+      "owner_section": "## Stub Detection",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "verification-legacy-deprecated-detection",
+      "text": "When reviewing or modifying any file, scan for legacy indicators",
+      "owner_file": "content/verification/verification.md",
+      "owner_section": "## Legacy and Deprecated Code Detection",
+      "authority": "SHOULD",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "glossary-ubiquitous-language",
+      "text": "**Ubiquitous language** \u2014 The shared, precisely defined vocabulary",
+      "owner_file": "content/glossary.md",
+      "owner_section": "## Framework Design Terms",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "glossary-rule-ownership-principle",
+      "text": "**Rule ownership** \u2014 The principle that each concept in directive has exactly one owning file",
+      "owner_file": "content/glossary.md",
+      "owner_section": "## Framework Design Terms",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "glossary-work-decomposition-hierarchy",
+      "text": "Release          \u2190 Shippable version (one or more features)",
+      "owner_file": "content/glossary.md",
+      "owner_section": "## Deft Work Decomposition Hierarchy",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "scm-git-conventional-commits",
+      "text": "use Conventional Commits format: `type(scope): description`",
+      "owner_file": "content/scm/git.md",
+      "owner_section": "## Standards",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "scm-git-safety-rules",
+      "text": "MUST NOT do without explicit permission",
+      "owner_file": "content/scm/git.md",
+      "owner_section": "## Safety Rules",
+      "authority": "MUST_NOT",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "scm-github-pr-merge-strategy",
+      "text": "Use squash-merge as the default merge method",
+      "owner_file": "content/scm/github.md",
+      "owner_section": "## PR Workflow Conventions",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "scm-github-post-merge-issue-verification",
+      "text": "After a PR is squash-merged, verify that all referenced issues were actually closed",
+      "owner_file": "content/scm/github.md",
+      "owner_section": "## Post-Merge Issue Verification",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "tools-taskfile-build-automation",
+      "text": "Use `task` for repeatable operations",
+      "owner_file": "content/tools/taskfile.md",
+      "owner_section": "## Task-Centric Workflow",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "vbrief-lifecycle-folders",
+      "text": "Individual units of work (features, bugs, initiatives) live as scope vBRIEFs in five lifecycle folders",
+      "owner_file": "content/vbrief/vbrief.md",
+      "owner_section": "## File Taxonomy",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "vbrief-filename-convention",
+      "text": "Scope vBRIEF filenames MUST follow: `YYYY-MM-DD-descriptive-slug.vbrief.json`",
+      "owner_file": "content/vbrief/vbrief.md",
+      "owner_section": "## File Taxonomy",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "resilience-session-continuity",
+      "text": "Persist to `./vbrief/continue.vbrief.json` in vBRIEF format",
+      "owner_file": "content/resilience/continue-here.md",
+      "owner_section": "## Continue Checkpoint Contents",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "context-engineering-write-strategy",
+      "text": "Externalize intermediate state so it doesn't consume context window",
+      "owner_file": "content/context/context.md",
+      "owner_section": "## Strategy 1: Write",
+      "authority": "SHOULD",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "swarm-explicit-context",
+      "text": "Never assume previous agent \"knew\" something implicit",
+      "owner_file": "content/swarm/swarm.md",
+      "owner_section": "## Communication Protocols",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "change-lifecycle-overview",
+      "text": "The active implementation is vBRIEF lifecycle first and Taskfile first",
+      "owner_file": "content/commands.md",
+      "owner_section": "## Overview",
+      "authority": "MUST",
+      "last_verified": "2026-06-17"
+    },
+    {
+      "id": "main-rule-authority-axiom",
+      "text": "Every rule MUST use the strongest applicable layer",
+      "owner_file": "main.md",
+      "owner_section": "## Rule Authority [AXIOM]",
+      "authority": "AXIOM",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "main-vbrief-persistence",
+      "text": "All vBRIEF files MUST be stored in `./vbrief/` or its lifecycle subfolders",
+      "owner_file": "main.md",
+      "owner_section": "## vBRIEF Persistence",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "agents-deft-alignment-confirmation",
+      "text": "confirm to the user that Deft Directive is active",
+      "owner_file": "AGENTS.md",
+      "owner_section": "### Deft Alignment Confirmation",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "agents-skill-completion-gate",
+      "text": "explicitly confirm skill exit and provide chaining instructions",
+      "owner_file": "AGENTS.md",
+      "owner_section": "## Skill Completion Gate",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "language-hygiene-python",
+      "text": "**Dead code:**",
+      "owner_file": "content/languages/python.md",
+      "owner_section": "## Hygiene",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "language-hygiene-go",
+      "text": "**Dead code:**",
+      "owner_file": "content/languages/go.md",
+      "owner_section": "## Hygiene",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "language-hygiene-typescript",
+      "text": "**Dead code:**",
+      "owner_file": "content/languages/typescript.md",
+      "owner_section": "## Hygiene",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "language-hygiene-javascript",
+      "text": "**Dead code:**",
+      "owner_file": "content/languages/javascript.md",
+      "owner_section": "## Hygiene",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "language-hygiene-rust",
+      "text": "**Dead code:**",
+      "owner_file": "content/languages/rust.md",
+      "owner_section": "## Hygiene",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "language-hygiene-cpp",
+      "text": "**Dead code:**",
+      "owner_file": "content/languages/cpp.md",
+      "owner_section": "## Hygiene",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "language-hygiene-csharp",
+      "text": "**Dead code:**",
+      "owner_file": "content/languages/csharp.md",
+      "owner_section": "## Hygiene",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "language-hygiene-java",
+      "text": "**Dead code:**",
+      "owner_file": "content/languages/java.md",
+      "owner_section": "## Hygiene",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "language-hygiene-kotlin",
+      "text": "**Dead code:**",
+      "owner_file": "content/languages/kotlin.md",
+      "owner_section": "## Hygiene",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "language-hygiene-swift",
+      "text": "**Dead code:**",
+      "owner_file": "content/languages/swift.md",
+      "owner_section": "## Hygiene",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "language-hygiene-c",
+      "text": "**Dead code:**",
+      "owner_file": "content/languages/c.md",
+      "owner_section": "## Hygiene",
+      "authority": "MUST",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "lesson-toolchain-validation-gate",
+      "text": "Before beginning any implementation phase, MUST verify that the complete toolchain",
+      "owner_file": "meta/lessons.md",
+      "owner_section": "## Toolchain Validation Gate (2026-03)",
+      "authority": "lesson",
+      "last_verified": "2026-04-28"
+    },
+    {
+      "id": "lesson-build-script-output-validation",
+      "text": "When modifying a build script, MUST verify that expected output artifacts exist",
+      "owner_file": "meta/lessons.md",
+      "owner_section": "## Build Script Output Validation (2026-03)",
+      "authority": "lesson",
+      "last_verified": "2026-04-28"
+    }
+  ]
+}

package/conventions/task-caching.md

@@ -0,0 +1,43 @@
+# Task Caching Convention
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**See also**: [main.md](../../main.md) | [tasks/prd.yml](../../tasks/prd.yml) | [tasks/scope.yml](../../tasks/scope.yml) | [tests/content/test_taskfile_caching.py](../../tests/content/test_taskfile_caching.py)
+
+## Invariant
+
+! Tasks in `deft/tasks/*.yml` that accept `{{.CLI_ARGS}}` containing user-facing recovery flags (any `--force`-like flag, or anything the script's error messages tell operators to pass) **MUST NOT** declare `sources:` or `generates:` keys.
+
+⊗ Declaring `sources:` / `generates:` on a task that forwards `{{.CLI_ARGS}}` to a Python script.
+
+## Why
+
+When both `sources:` and `generates:` are declared and every `generates` file exists with an unchanged `sources` hash, go-task short-circuits and skips `cmds:` entirely. `CLI_ARGS` are never relayed because the command is never invoked. The script-level recovery flag therefore never reaches the script, and the operator hits a silent `"task: Task \"<name>\" is up to date"` exit 0 while following deft's own documented recovery instruction.
+
+This is what broke `task prd:render -- --force` for every migrating consumer with a pre-existing `PRD.md` on `phase2/vbrief-cutover`: the `#539` refuse-to-overwrite safety check instructs operators to "Re-run with --force to overwrite", but the `prd:render` task short-circuited at the go-task cache layer before `cmds:` ran, so `prd_render.py` never saw `--force` (#574).
+
+## Scope
+
+The invariant applies specifically to tasks whose **command line forwards `{{.CLI_ARGS}}` to a dispatched Python script** (`uv run python ... {{.CLI_ARGS}}`). These tasks are the recovery-flag carriers and are the ones whose semantics break when go-task short-circuits.
+
+Tasks that do not forward `{{.CLI_ARGS}}` (e.g. pure file-copy / archive-extraction pipelines like `deployments:cloudgov:export`) are **not** subject to this invariant -- their caching behavior is correct because they do not carry user-recovery semantics.
+
+## Exception discipline
+
+~ When a task is genuinely cache-worthy (e.g. an expensive compile, a large archive extraction) AND does NOT accept `CLI_ARGS` recovery flags, `sources:` / `generates:` MAY be declared. In that case:
+
+1. ! Document the justification in an inline comment at the task declaration explaining why caching is safe for this task.
+2. ! Append an entry to this file (under an "Exceptions" subsection) documenting the task and the justification so future contributors can audit cache-declarations centrally.
+
+The pattern for the current single exception in `tasks/deployments.yml` (`cloudgov:sync`, `cloudgov:export`) is: neither task forwards `CLI_ARGS`; both operate over a fixed upstream pin and a fixed set of instruction files, so the cache correctly represents the task's output.
+
+## Guard-rail
+
+The invariant is enforced by `tests/content/test_taskfile_caching.py`, parametrized over every `deft/tasks/*.yml`. For each task that (a) invokes a Python script via `uv run python` AND (b) forwards `{{.CLI_ARGS}}` to that script, the test asserts the task declaration does NOT contain `sources:` or `generates:` keys. The failure message points contributors back at this file.
+
+## Cross-references
+
+- #539 -- refuse-to-overwrite safety feature whose `--force` recovery instruction lives in PRD/spec render scripts
+- #573 -- broader ergonomics discussion about double-`--force` layering (deferred post-GA)
+- #574 -- this rule's immediate motivating fix (drop caching from `tasks/prd.yml`)
+- #566 / #568 -- sibling Windows-dispatch guard-rail pattern (`tests/content/test_taskfile_paths.py`) this rule's test module mirrors

package/conventions/vbrief-filenames.md

@@ -0,0 +1,70 @@
+# vBRIEF Filename Conventions
+
+Canonical rules for scope vBRIEF filenames and slug normalization.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**See also**: [../vbrief/vbrief.md](../vbrief/vbrief.md) | [./references.md](./references.md) | [../main.md](../../main.md)
+
+---
+
+## Filename Shape
+
+Scope vBRIEFs in `vbrief/proposed/`, `vbrief/pending/`, `vbrief/active/`, `vbrief/completed/`, and `vbrief/cancelled/` follow the pattern:
+
+```
+YYYY-MM-DD-<slug>.vbrief.json
+```
+
+- ! The leading date is the **creation date** in `YYYY-MM-DD` form. It is immutable — it MUST NOT change as the scope moves through the lifecycle.
+- ! The `<slug>` is a lowercase hyphen-separated descriptor derived from the scope title (or origin issue title for ingested vBRIEFs).
+- ! The filename MUST end in `.vbrief.json`.
+- ! The filename MUST match `scripts/vbrief_validate.py`'s `FILENAME_PATTERN`: `^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*\.vbrief\.json$`.
+
+speckit Phase 4 scope vBRIEFs use the extended pattern `YYYY-MM-DD-ip<NNN>-<slug>.vbrief.json` where `<NNN>` is the implementation-phase index zero-padded to exactly three digits (e.g. `ip001`, `ip042`, `ip128`). See [`../vbrief/vbrief.md`](../vbrief/vbrief.md#speckit-phase-4-scope-vbriefs) for detail.
+
+## Slug Normalization Rules
+
+`scripts/slug_normalize.py` exposes the canonical `normalize_slug(title, issue_number=None)` function. Every tool or skill that coins a scope vBRIEF filename MUST either call that function or apply the same rules documented below so that two different producers always agree on the slug for the same title.
+
+The rules, applied in order:
+
+1. ! **Lowercase** the full input string.
+2. ! **Strip GitHub issue-number prefixes** like `#123 ` or `123: ` from the start of the title before slugging (they belong in the date prefix and the references, not in the slug).
+3. ! **Replace non-ASCII letters** with their closest ASCII equivalent when possible (e.g. `é` → `e`). Characters without a reasonable fold are dropped.
+4. ! **Replace runs of non-alphanumeric characters** (whitespace, punctuation, emoji, quotes) with a single hyphen (`-`).
+5. ! **Collapse runs of hyphens** into a single hyphen.
+6. ! **Strip leading and trailing hyphens**.
+7. ! **Truncate** the slug at a natural hyphen boundary so the final slug is no longer than **80 characters**. Do not cut in the middle of a word when a hyphen boundary is available within the last 20 characters.
+8. ~ **Append `-issue-<N>`** (when an origin issue number is provided and the suffix is not already present) so ingested vBRIEFs carry their origin ID in the filename. Skills MAY opt out when the issue number is already captured elsewhere and the slug would otherwise become awkward.
+9. ! **Guarantee at least one alphanumeric character** in the output — if the normalized result is empty (e.g. the title was all punctuation), fall back to `scope` (or `scope-<issue-number>` when available).
+10. ⊗ Include the `YYYY-MM-DD-` date prefix in `normalize_slug` output — the caller prepends the date.
+
+### Examples
+
+| Input title | Issue | Output slug |
+| --- | --- | --- |
+| `Fix login bug` | (none) | `fix-login-bug` |
+| `"Evolution" client API calls lack pagination` | `#19` | `evolution-client-api-calls-lack-pagination-issue-19` |
+| `docs: 12 broken internal links in deft docs surfaced by its own verify:links tool` | `#541` | `docs-12-broken-internal-links-in-deft-docs-surfaced-by-its-own-verify-links-tool-issue-541` |
+| `🚨 Pre-Flight requires GitHub PULL_REQUEST_TEMPLATE.md but ...` | `#531` | `pre-flight-requires-github-pull-request-template-md-but-issue-531` |
+
+## Dedup Contract
+
+- ! Consumers (skills + tasks) MUST use the same slug for the same title so that `task issue:ingest` and the deft-directive-refinement skill agree on dedup keys.
+- ! Dedup is primarily driven by origin `references.uri` matching; slug agreement is the secondary safeguard.
+- ⊗ Invent ad-hoc title → slug transformations inside skills — call `normalize_slug` instead.
+
+## When You Need to Rename
+
+Scope vBRIEF filenames are part of the file's identity. Renames MUST preserve the date prefix and keep the slug stable whenever possible:
+
+- ! When the origin title changes substantially, prefer keeping the original slug rather than churning filenames; update `plan.title` in place and rely on the reference `uri` for traceability.
+- ! If a rename is unavoidable, update every `planRef` and `references[].uri` pointing at the old path in the same commit (see `vbrief/vbrief.md` § Status-Driven Moves).
+
+## Anti-Patterns
+
+- ⊗ Use uppercase letters, underscores, or camelCase in the slug
+- ⊗ Put the origin issue number in the date segment (`2026-04-22-#541-...`) — the issue number belongs in the suffix (`...-issue-541`) or in `references`
+- ⊗ Change the date prefix when a scope moves between lifecycle folders — the date is the creation date, not the current-status date
+- ⊗ Coin slugs by hand inside skills; call `scripts/slug_normalize.py` (`normalize_slug`) instead

package/deployments/README.md

@@ -0,0 +1,37 @@
+# Deployments Layer
+
+Platform-specific guidance for deployment environments (cloud.gov, Cloudflare, AWS, agentuity, etc.).
+
+## Purpose
+
+- ! Provide **optional** platform modules that can be applied per project
+- ~ Keep platform guidance separate from core Deft rules
+- ~ Enable export of platform instructions for external tools (e.g., Copilot)
+
+## Module Structure
+
+Create a directory per platform:
+
+```
+deployments/
+  <platform>/
+    README.md
+    overview.md
+    deployment.md
+    manifest.md
+    services.md
+    cicd.md
+    security.md
+    logging.md
+    agents.md
+    agents/
+    skills/
+    upstream/
+```
+
+Guidelines:
+
+- ! Use hyphens in filenames
+- ! Keep modules optional and isolated
+- ~ Include a clear README with attribution (if derived)
+- ~ Provide export tasks that generate tool-specific outputs

package/deployments/agentuity/README.md

@@ -0,0 +1,138 @@
+# Agentuity Deployment Module
+
+Deft guidance for deploying AI agents to Agentuity, the full-stack platform built for autonomous agents.
+
+## Status
+
+- ! Optional module
+- ~ Good for Deft usage
+
+## Overview
+
+<cite index="1-1,1-2,1-3">Agentuity is a full-stack platform for building sophisticated AI agents with intelligent routing, persistent state, and seamless handoffs, deploying with built-in APIs, React frontends, databases, and monitoring, and running on their cloud, your VPC, or on-premises.</cite> Launched in February 2026, <cite index="6-8,6-9">Agentuity enables streamlined creation of fully functional and easy-to-manage agents through purpose-built primitives for agentic software, including built-in storage services, secure code execution sandboxes, production evaluations, and the ability to deploy anywhere from public cloud to on-premises infrastructure.</cite>
+
+## Deployment Methods
+
+| File | Method | Best For |
+|------|--------|----------|
+| `via-cli.md` | Agentuity CLI | Primary deployment method, local dev to production |
+| `via-cloud.md` | Agentuity Managed Cloud | Simplest path, global edge network |
+| `via-vpc.md` | Private VPC / On-Prem | Enterprise security, data sovereignty |
+| `via-github-actions.md` | GitHub Actions CI/CD | Automated deployments, push-to-deploy |
+| `via-gravity-network.md` | Gravity Network | Multi-cloud, edge, hybrid deployments |
+
+## Supported Frameworks
+
+<cite index="1-10,1-11">Agentuity wraps your existing agent code with observability, evals, streaming, and auth without forcing a new runtime, supporting Mastra, AI SDK, or your own code.</cite>
+
+- **Vercel AI SDK** — Full TypeScript support with type-safe schemas
+- **Mastra** — Agent orchestration framework
+- **LangChain** — Python and TypeScript agent frameworks
+- **LlamaIndex** — RAG and data framework agents
+- **Custom Agents** — Bring your own agent implementation
+
+## Deployment Approaches
+
+### CLI Deployments
+
+```bash
+# Install Agentuity CLI
+curl -fsS https://agentuity.sh | sh
+
+# Create new project
+agentuity create
+
+# Start local development
+agentuity dev
+
+# Deploy to cloud
+agentuity deploy
+```
+
+### Git-Based Deployments
+
+<cite index="1-16">Push to main and GitHub auto-deploys</cite> — connect your repository and Agentuity automatically deploys on every push to your main branch.
+
+### Full-Stack Development
+
+- **Type-safe APIs**: Hono routes that auto-generate React hooks
+- **React Frontends**: Deploy React apps with end-to-end type safety
+- **Built-in Services**: Redis, Postgres, vector storage, object storage
+- **Sandboxes**: Isolated containers for secure code execution
+
+### Multi-Environment Support
+
+<cite index="1-3,1-18">Run on Agentuity cloud, your VPC, or on-prem, with deployment to public cloud, private cloud, on-premises, multi-cloud, or edge — one platform, one SDK, one consistent developer experience.</cite>
+
+## Quick Decision Guide
+
+- **Fastest start**: `via-cloud.md` — deploy to managed infrastructure with one command
+- **Enterprise security**: `via-vpc.md` — private cloud or on-premises deployment
+- **CI/CD pipelines**: `via-github-actions.md` — automated deployments
+- **Local development**: Agentuity CLI — offline-ready, no account required
+- **Multi-cloud**: `via-gravity-network.md` — deploy anywhere with Gravity Network
+- **Full-stack apps**: CLI + React SDK — agents, APIs, and frontends together
+
+## Key Features
+
+### Agent-Native Infrastructure
+
+- **Long-running runtimes**: Agents can run for minutes or hours
+- **Stateful orchestration**: Persistent state and session management
+- **Agent-to-agent communication**: Type-safe calls between agents
+- **Production evaluations**: Evals run on live traffic
+
+### Built-In Services
+
+- **Storage**: Key-value, vector, Postgres, S3-compatible object storage
+- **Sandboxes**: Secure code execution environments
+- **AI Gateway**: Unified access to OpenAI, Anthropic, Google, Groq, Mistral
+- **Observability**: OpenTelemetry tracing, logging, cost tracking
+
+### Developer Experience
+
+- **Offline-ready**: Start building without an account
+- **Type safety**: End-to-end TypeScript support
+- **Hot reload**: Instant feedback in development
+- **One-command deploy**: From dev to production instantly
+
+### Enterprise Features
+
+- **VPC deployment**: Run in your private cloud
+- **On-premises**: Deploy to your own infrastructure
+- **SSO integration**: Enterprise authentication
+- **Compliance**: SOC 2, GDPR, HIPAA ready
+
+## Platform Comparison
+
+<cite index="10-9">Agentuity aims to make AWS, Azure, and Google Cloud feel like legacy systems for the old app world, positioning Agentuity as synonymous with the next generation of cloud infrastructure: an AI-native platform that meets the unique demands of this technology.</cite>
+
+**Traditional clouds** (AWS, Azure, GCP) are optimized for request-response workloads. <cite index="9-5">Agents don't exclusively fit execution models built around short-lived requests — they reason, iterate, pause, resume, run for seconds or minutes or hours at a time, manage context, spawn other agents, and adapt their behavior as they go.</cite>
+
+## References
+
+- [Agentuity Documentation](https://agentuity.dev/)
+- [Agentuity CLI GitHub](https://github.com/agentuity/cli)
+- [Getting Started Guide](https://agentuity.dev/Introduction/getting-started)
+- [SDK Explorer](https://agentuity.dev/)
+- [Examples Repository](https://github.com/agentuity/examples)
+- [Agents Spotlight](https://agentuity.com/spotlight)
+
+<citations>
+  <document>
+    <document_type>WEB_SEARCH_RESULT</document_type>
+    <document_id>1</document_id>
+  </document>
+  <document>
+    <document_type>WEB_SEARCH_RESULT</document_type>
+    <document_id>6</document_id>
+  </document>
+  <document>
+    <document_type>WEB_SEARCH_RESULT</document_type>
+    <document_id>9</document_id>
+  </document>
+  <document>
+    <document_type>WEB_SEARCH_RESULT</document_type>
+    <document_id>10</document_id>
+  </document>
+</citations>