@deftai/directive-content 0.55.0

package/docs/BROWNFIELD.md

@@ -0,0 +1,179 @@
+# Adding Deft to an Existing Project (Brownfield Adoption)
+
+Adding Deft to an existing codebase is the harder path and the one most likely to go wrong without guidance. This guide walks you through the steps, what changes, and how to preserve existing spec content.
+
+**Greenfield users:** If you are starting a new project from scratch, follow the [Getting Started](../../README.md#-getting-started) flow in the README instead. This guide is only for projects that already have code, docs, or a pre-v0.20 Deft layout.
+
+> **See also:** [README.md](../../README.md), [QUICK-START.md](../QUICK-START.md), [vbrief/vbrief.md](../vbrief/vbrief.md), and `UPGRADING.md` at the repo root (added in v0.20 -- issue #411).
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+---
+
+## 1. Install Deft in Your Project
+
+You have three ways to add the `deft/` framework to an existing project. Pick the one that fits your workflow:
+
+### Option A: Git submodule (recommended)
+
+```bash
+git submodule add https://github.com/deftai/directive.git deft
+git submodule update --init --recursive
+```
+
+- ~ Pin to a release tag so framework updates are explicit:
+  ```bash
+  cd deft && git checkout v0.20.0 && cd ..
+  git add deft && git commit -m "chore(deft): pin framework to v0.20.0"
+  ```
+- ~ Update later with `cd deft && git fetch && git checkout <new-tag>`.
+- ! Commit the submodule pointer after every version bump so teammates do not drift.
+
+### Option B: Installer binary
+
+If you downloaded the Deft installer (see [GitHub Releases](https://github.com/deftai/directive/releases)), run it against your existing project directory:
+
+```bash
+./install-<platform>-<arch>
+```
+
+- The installer clones `deft/` into the project root, wires it into `AGENTS.md` (append-mode if the file already exists), and creates your user config directory.
+- Your existing `AGENTS.md` content is preserved; Deft entries are appended with two blank lines before them.
+
+### Option C: Direct clone (no installer, no submodule)
+
+```bash
+git clone https://github.com/deftai/directive.git deft
+```
+
+- ~ Fine for experimentation; use submodule or installer for anything durable.
+- ! Tell your agent: "Read `deft/QUICK-START.md` and follow it." QUICK-START creates your `AGENTS.md` idempotently.
+
+---
+
+## 2. Migrate Existing Docs (`task migrate:vbrief`)
+
+If your project already contains `SPECIFICATION.md`, `PROJECT.md`, or `ROADMAP.md`, run the one-shot migration:
+
+```bash
+task migrate:vbrief
+```
+
+The migration is **idempotent** -- safe to re-run on a partially-migrated project.
+
+### What migration does
+
+1. **Parses** existing `specification.vbrief.json` (if present) + `PROJECT.md` and generates `vbrief/PROJECT-DEFINITION.vbrief.json` with a `narratives` map (project identity) and an `items` registry (scope).
+2. **Creates** the five lifecycle folders: `vbrief/proposed/`, `vbrief/pending/`, `vbrief/active/`, `vbrief/completed/`, `vbrief/cancelled/`.
+3. **Converts** `ROADMAP.md` items into individual `pending/` scope vBRIEFs with origin provenance (`references` array pointing back to GitHub issue numbers, if available).
+4. **Replaces** `SPECIFICATION.md` and `PROJECT.md` with deprecation redirect stubs containing `<!-- deft:deprecated-redirect -->` -- the sentinel that tells future `task vbrief:validate` runs these files are no longer authoritative.
+5. **Preserves** user-customized content it cannot parse: anything non-standard in `PROJECT.md` is stored in a `ProjectConfig` narrative on `PROJECT-DEFINITION.vbrief.json` instead of being discarded.
+
+### Preserving existing spec content (#397 ingestion)
+
+`task migrate:vbrief` also reads structured `## ` sections from `PRD.md` and `SPECIFICATION.md` (Problem Statement, Goals, User Stories, Requirements, Success Metrics, Non-Functional Requirements, Open Questions) and maps them to canonical narrative keys on `vbrief/specification.vbrief.json`. Existing keys are never overwritten.
+
+- ~ Review the generated `vbrief/specification.vbrief.json` after migration; fill in any narrative the parser could not map.
+- ~ If the parser missed content you care about, copy it into the appropriate narrative before deleting the old file backup.
+
+---
+
+## 3. What Changes After Migration
+
+### Source of truth: `.vbrief.json` files
+
+- `vbrief/PROJECT-DEFINITION.vbrief.json` replaces `PROJECT.md` as the project identity gestalt (tech stack, strategy, coverage, architecture, branching convention).
+- `vbrief/specification.vbrief.json` replaces `SPECIFICATION.md` as the project spec source of truth.
+- Individual units of work live in `vbrief/{proposed,pending,active,completed,cancelled}/` as `YYYY-MM-DD-<slug>.vbrief.json`.
+
+### Rendered views: `.md` artifacts
+
+`.md` files like `PRD.md`, `SPECIFICATION.md`, and `ROADMAP.md` become **rendered views**, generated on demand:
+
+```bash
+task spec:render         # vbrief/specification.vbrief.json -> SPECIFICATION.md
+task prd:render          # vbrief/specification.vbrief.json narratives -> PRD.md
+task roadmap:render      # vbrief/pending/ scope vBRIEFs -> ROADMAP.md
+task project:render      # lifecycle folders -> PROJECT-DEFINITION.vbrief.json items registry
+```
+
+- ⊗ Edit the rendered `.md` files directly -- your changes are overwritten on the next `task *:render` run.
+- ! Edit the underlying `.vbrief.json` instead, then run `task *:render` to refresh the export.
+- ~ `task spec:render` and `task prd:render` are also invoked automatically by `skills/deft-directive-pre-pr/SKILL.md` Phase 3b if the export files already exist.
+
+### Deprecation sentinels
+
+After migration, the root `SPECIFICATION.md` and `PROJECT.md` contain a redirect stub with a sentinel comment on its first line followed by a short pointer. The exact output is produced by `_deprecation_redirect()` in `scripts/migrate_vbrief.py`; the first line is always `<!-- deft:deprecated-redirect -->`, which is the only line `scripts/vbrief_validate.py` checks. A simplified representation:
+
+```markdown
+<!-- deft:deprecated-redirect -->
+# PROJECT.md -- DEPRECATED
+
+This file has been migrated to `vbrief/PROJECT-DEFINITION.vbrief.json`.
+
+**See instead:**
+- `vbrief/PROJECT-DEFINITION.vbrief.json` (project identity)
+- scope vBRIEFs in `vbrief/{proposed,pending,active,completed,cancelled}/`
+```
+
+(The actual generated body may include additional context; the sentinel comment on line 1 is what the validator enforces.)
+
+`scripts/vbrief_validate.py` warns if these files exist without the sentinel; `skills/deft-directive-build/SKILL.md` Pre-Cutover Detection Guard redirects to `task migrate:vbrief` if it detects pre-v0.20 state on first setup.
+
+---
+
+## 4. Pre-Cutover Detection Guard
+
+On first interactive session after adding Deft, the agent-driven path runs a **pre-cutover detection guard** from `skills/deft-directive-setup/SKILL.md` and `skills/deft-directive-build/SKILL.md`. The guard detects legacy artifacts and redirects to the migration command instead of silently proceeding with a mismatched project layout.
+
+**Detection criteria** (any one triggers the guard):
+
+1. `SPECIFICATION.md` exists and does **not** contain `<!-- deft:deprecated-redirect -->`.
+2. `PROJECT.md` exists and does **not** contain `<!-- deft:deprecated-redirect -->`.
+3. `vbrief/specification.vbrief.json` exists but the lifecycle folders (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`) do **not**.
+
+**Action on detection:** the agent stops with an actionable message such as "Run `task migrate:vbrief` to upgrade to the vBRIEF-centric model."
+
+### CLI path (`.deft/core/run`)
+
+The CLI has a companion non-fatal upgrade gate (issue #410): `.deft/core/run` warns on every invocation when `vbrief/.deft-version` does not match the framework `VERSION`, or when legacy artifacts are found without the sentinel. Interactive sessions get a `Continue anyway? [y/N]` prompt; non-interactive sessions (CI, cloud agents) warn once and continue so CI is never blocked.
+
+After completing migration, record the framework version so the CLI gate stays silent:
+
+```bash
+.deft/core/run upgrade         # writes vbrief/.deft-version = <current VERSION>
+```
+
+---
+
+## 5. Post-Migration Checklist
+
+Run these in order once `task migrate:vbrief` completes:
+
+1. ! `task vbrief:validate` -- should report zero errors and zero warnings about `SPECIFICATION.md` / `PROJECT.md`. Deprecation-sentinel warnings from `scripts/vbrief_validate.py` fire when the sentinel is **missing** from those files -- if you see them, the redirect stubs were not written correctly and the migration is incomplete; re-run `task migrate:vbrief` or patch the stubs to include the `<!-- deft:deprecated-redirect -->` line.
+2. ! `task check` -- the full pre-commit pipeline (fmt + lint + typecheck + tests + coverage + vbrief validation + link check). Must be green before your first Deft-aware commit.
+3. ~ `task project:render` -- regenerate `vbrief/PROJECT-DEFINITION.vbrief.json` items registry to reflect the newly-migrated scopes.
+4. ~ `task roadmap:render` and `task spec:render` -- refresh the rendered views so teammates browsing the repo see current content.
+5. ~ Review the generated `vbrief/proposed/` and `vbrief/pending/` scope vBRIEFs; promote / activate / cancel them as appropriate via `task scope:promote|activate|complete|cancel|restore|block|unblock`.
+6. ~ Commit the migration in a focused PR with a conventional-commit subject such as `chore(deft): migrate to vBRIEF-centric document model (v0.20)`.
+
+---
+
+## 6. Troubleshooting
+
+- **`task vbrief:validate` fails on my scope vBRIEFs:** filename must follow `YYYY-MM-DD-<lowercase-slug>.vbrief.json` (D7); folder must match `plan.status` (D2); PROJECT-DEFINITION must have `overview` and `tech stack` narrative keys after `.lower()` (D3).
+- **`task migrate:vbrief` did not migrate my roadmap:** the migration parser recognises task-based (`- \`X.Y.Z\` Title`) and plain (`- Title`) list item formats under `## ` headings. Custom formats fall through to synthetic IDs -- review the generated vBRIEFs and rename / reshape as needed.
+- **My agent hits a missing `deft/skills/deft-*/` path:** that is a stale v0.19 `AGENTS.md` from before the `deft-directive-*` rename. Tell your agent "Read `deft/QUICK-START.md` and follow it" -- QUICK-START refreshes the Deft-managed section of `AGENTS.md` idempotently. See `UPGRADING.md` (present in repositories on v0.20 or later) for the detailed upgrade flow.
+- **I edited `SPECIFICATION.md` by accident:** revert the file to the redirect stub (`<!-- deft:deprecated-redirect -->` + the three-line note), then edit `vbrief/specification.vbrief.json` and run `task spec:render`.
+
+---
+
+## 7. Related Reading
+
+- [README.md](../../README.md) -- product overview and greenfield flow.
+- [QUICK-START.md](../QUICK-START.md) -- agent bootstrap (also handles the brownfield AGENTS.md append case).
+- [vbrief/vbrief.md](../vbrief/vbrief.md) -- canonical vBRIEF file taxonomy, lifecycle folders, and status mapping.
+- [commands.md](../commands.md) -- full `run` vs `task` command lifecycle.
+- `skills/deft-directive-build/SKILL.md` -- Pre-Cutover Detection Guard implementation.
+- `skills/deft-directive-setup/SKILL.md` -- greenfield path for comparison.
+- `UPGRADING.md` (repo root, v0.20+) -- version-by-version upgrade guide.

package/docs/getting-started.md

@@ -0,0 +1,137 @@
+# Getting Started with Deft Directive
+
+Deft Directive is a Taskfile-first framework for AI-assisted software work. It combines agent guidance, deterministic gates, vBRIEF lifecycle metadata, installer/doctor handoff, and cache-backed backlog workflows. This guide walks through installation, preferences, project setup, and the first scope workflow.
+
+> **Note**: This guide is an orientation layer. For current architecture details, see [ARCHITECTURE.md](../../docs/ARCHITECTURE.md); for command behavior, see [commands.md](../commands.md).
+
+## Deft & Directive (naming)
+
+**Deft is the company; Directive is the product.** *Deft* names the organization and the on-disk footprint (`.deft/`, `@deftai/*` npm scope, user config under `~/.config/deft/`). *Directive* names the framework you install and run: the npm package is `@deftai/directive`, and the primary CLI is `directive` (`deft` is an alias). Legacy `deft-install` / `deft` paths in this guide refer to the same product during the staged transition ([#423](https://github.com/deftai/directive/issues/423)).
+
+---
+
+## Prerequisites
+
+- **Node 20+** and **pnpm** for live gates and the npm distribution channel (see `.nvmrc` in the framework payload).
+- **Go 1.22+** only if you use the bootstrap Go installer or build from source.
+- **Python 3.11+**, **uv**, **task**, **git**, and **gh** for full framework workflows — run `directive toolchain:check` (or `deft toolchain:check`) after install.
+
+---
+
+## Installation
+
+### npm (coming soon — not yet published)
+
+> ⚠️ **The `@deftai/directive` npm package is not yet published** to the registry (provisioning tracked by [#1909](https://github.com/deftai/directive/issues/1909)). **Until it goes live, install via the [Go installer](#go-installer-bootstrap) below.** The commands shown here are what the install will become once the package is published.
+
+<!-- TODO(#1909): flip to npm-canonical and remove this "coming soon" notice when @deftai/directive is published -->
+
+Once published, when Node is already available you will install Directive globally:
+
+```bash
+npm i -g @deftai/directive
+directive --version    # primary command
+deft --version         # alias — same binary
+```
+
+One-shot without a global install (also once published):
+
+```bash
+npx @deftai/directive doctor
+npx @deftai/directive session:start
+```
+
+This npm path is the emerging primary distribution channel under `@deftai/directive` ([#11](https://github.com/deftai/directive/issues/11)); the Go installer below remains the install/bootstrap option today and during the staged retire window.
+
+### Go installer (bootstrap)
+
+Download a platform installer from the [Directive release page](https://github.com/deftai/directive/releases) and run it from the project you want to adopt:
+
+```bash
+deft-install --yes --repo-root . --json
+```
+
+For existing consumer projects, the headless upgrade path is:
+
+```bash
+deft-install --yes --upgrade --repo-root . --json
+```
+
+Those consumer flows intentionally project Deft-managed files into your project
+root (`AGENTS.md`, skills pointers, gitignore entries, vbrief scaffolding, and
+related guard configuration). Framework maintainers working inside a
+`deftai/directive` checkout should instead follow
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) and use `--maintainer`; maintainer setup
+checks tools without rewriting consumer-managed files.
+
+---
+
+## First Project
+
+<!-- TODO: Walk through deft-setup phases: USER.md, PROJECT.md, SPECIFICATION.md -->
+
+---
+
+## Working an existing backlog
+
+If you are adopting Deft on a project that already has an issue tracker (existing repo, brownfield migration, an upstream bug list that has been accumulating), you do not have to start from an empty `vbrief/proposed/`. The refinement skill's **Phase 0 triage workflow** lets you walk an existing backlog locally, decide what to keep, and let only the **accepted** items land in `vbrief/proposed/`. Trigger words: **"triage"**, **"work the cache"**, **"pre-ingest"**, **"action menu"**.
+
+### Step 1 — Scoped first populate
+
+A real-sized backlog can drain the shared GitHub GraphQL bucket if you fetch everything at once (see [#976](https://github.com/deftai/directive/issues/976) for the recurring symptom). Scope the first populate so it lands in seconds rather than minutes:
+
+```bash
+task triage:bootstrap -- --limit 50 --state open
+```
+
+Flag surface (shared by `task triage:bootstrap` and `task cache:fetch-all`):
+
+- `--limit <N>` caps the number of issues fetched (start with `50` and widen as needed).
+- `--state {open|closed|all}` selects the issue state (default `open`).
+- `--batch-size <N>` caps the per-page fetch (default `10`).
+- `--delay-ms <N>` inserts a sleep between batches so a populate against a large repo does not trip the rate limiter (default `500`; a `429` retries automatically using the upstream `Retry-After` header).
+- `--repo OWNER/NAME` is optional; when omitted, the bootstrap infers the slug from `git remote get-url origin`.
+
+The unbounded no-flag form remains the default for small backlogs. For real-sized repos, prefer the scoped first run; you can always re-enter triage later to widen the slice.
+
+### Step 2 — Walk the action menu
+
+After the cache is populated, ask your agent to triage. For each cached candidate the agent presents a numbered action menu and waits for your decision:
+
+```
+1. Accept         -- task triage:accept <issue>          (writes proposed/ vBRIEF + audit-log entry)
+2. Reject         -- task triage:reject <issue>          (audit-log entry only; closes the upstream issue)
+3. Defer          -- task triage:defer <issue>           (non-terminal; resurfaces on the next pass)
+4. Needs-AC       -- task triage:needs-ac <issue>        (non-terminal; flags missing acceptance criteria)
+5. Mark duplicate -- task triage:mark-duplicate <a> <b>  (terminal; cross-links the duplicate target)
+6. Discuss
+7. Back
+```
+
+Only **accepted** items become scope vBRIEFs in `vbrief/proposed/`. Rejected, deferred, and duplicate decisions are recorded in the audit log so the backlog stays focused. Bulk verbs (`task triage:bulk-accept` / `bulk-reject` / `bulk-defer` / `bulk-needs-ac`) handle predictable patterns (e.g. "reject every `wontfix`-labelled candidate") without walking the menu N times.
+
+### Step 3 — Understand the three-tier model
+
+Phase 0 reads and writes three distinct stores; they never collapse into one:
+
+- **Cache** — `.deft-cache/github-issue/<owner>/<repo>/<N>/` is the local mirror of fetched issue bodies, labels, and state. Populated by `task cache:fetch-all`; read via `task cache:get -- github-issue OWNER/NAME/<N>`. The directory is gitignored — your local mirror is private to your machine. The cache is the **read** surface for triage so decisions are reproducible across re-runs (no live `gh issue view` per decision).
+- **Audit log** — `vbrief/.eval/candidates.jsonl` is an append-only JSONL recording every candidate you have ever seen plus the action taken (`accept | reject | defer | needs-ac | mark-duplicate`) and a timestamp. Re-running triage against the same cache short-circuits items that already have a terminal entry, so deferred / Needs-AC items resurface and rejected ones do not.
+- **Accepted backlog** — `vbrief/proposed/` is the standard scope-vBRIEF lifecycle folder. **Writes flow only through `task triage:accept`**, which delegates the actual vBRIEF authoring to `task issue:ingest` so slug, reference, and schema rules stay in one place. Hand-authored proposed/ vBRIEFs are still allowed; what changed is that triage no longer writes there silently.
+
+### Step 4 — Why this avoids the GraphQL drain
+
+The shared GitHub GraphQL bucket (5000 points/hour per identity) is the operational bottleneck under multi-agent / shared-identity workflows, not the REST `core` bucket. The triage cache is **REST-backed** (`gh api` reads, not `gh issue view --json`), and the populate uses **batched delays** plus automatic 429 retries with the upstream `Retry-After` header. There is no live `gh issue view` per accept / reject / defer decision — every decision reads from the local cache. This is why the scoped flags exist: they let you keep the populate inside the REST budget and well clear of the GraphQL bottleneck (see [#976](https://github.com/deftai/directive/issues/976) for the recurrence pattern). Refresh the cache on demand with `task cache:fetch-all` (idempotent — fresh entries are skipped) or audit drift against `vbrief/active/*.vbrief.json` with `task triage:refresh-active`.
+
+Full command reference for every triage and cache verb lives in [`commands.md` § Backlog triage & cache tasks](../commands.md#backlog-triage--cache-tasks); the canonical agent-facing description of the workflow lives in `skills/deft-directive-refinement/SKILL.md` Phase 0.
+
+---
+
+## Using Strategies
+
+<!-- TODO: Introduce strategy selection, chaining gate, and common workflows (interview, rapid, enterprise) -->
+
+---
+
+## Agent Configuration
+
+<!-- TODO: Cover AGENTS.md, skill routing, Warp Drive integration, and cloud agent dispatch -->

package/docs/good-agents-md.md

@@ -0,0 +1,137 @@
+# A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all.
+
+**Source**: https://x.com/augmentcode/status/2047164534310494709  
+**Author**: Slava Zhenylenko (Member of Technical Staff, Augment Code)  
+**Published**: 2026-04-23
+
+---
+
+We pulled dozens of AGENTS.md files from across our monorepo and measured their effect on code generation. The best ones gave our coding agent a quality jump equivalent to upgrading from Haiku to Opus. The worst ones made the output worse than having no AGENTS.md at all.
+
+That gap was surprising enough that we built a systematic study around it.
+
+What we found: most of what people put in AGENTS.md either doesn't help or actively hurts, and the patterns that work are specific and learnable.
+
+## The same file can help one task and hurt another by 30%
+
+A single AGENTS.md isn't uniformly good or bad. The same file boosted best_practices by 25% on a routine bug fix and dropped completeness by 30% on a complex feature task in the same module.
+
+On the bug fix, a decision table for choosing between two similar data-fetching approaches helped the agent pick the right pattern immediately and stay within codebase standards. On the feature task, the agent read that same file, got pulled into the reference section, opened dozens of other markdown files trying to verify its approach against every guideline, created unnecessary abstractions, and shipped an incomplete solution.
+
+Different blocks of the document had opposite effects on different tasks.
+
+What follows is which patterns work, which fail, and how to tell which is which for your codebase.
+
+## How we measured this
+
+We used AuggieBench, one of our internal eval suites, to evaluate how well agents do our internal dev work. We start with high-quality PRs from a large repo that reflect typical day-to-day agent tasks, set up the environment and prompt, and ask the agent to do the same task. Then we compare its output against the golden PR, the version that actually landed after review by multiple senior engineers. We filtered out PRs with scope creep or known bugs.
+
+For this study, we added two more filters: PRs had to be contained within a single module or app, and the scope had to be one where information in an AGENTS.md might plausibly help. We then ran each task twice, with and without the file, and compared scores.
+
+## What works
+
+### 1. Progressive disclosure beats comprehensive coverage
+
+Treat your AGENTS.md like a skill. Cover the common cases and workflows at a high level, then push details into reference files the agent can load on demand. Keep each reference's scope clear so the agent knows when to pull it in.
+
+The 100–150 line AGENTS.md files with a handful of focused reference documents were the top performers in our study, delivering 10–15% improvements across all metrics in mid-size modules of around 100 core files. Once the main file got longer than that, the gains started reversing.
+
+### 2. Procedural workflows take agents from failing to finishing
+
+Describing a task as a numbered, multi-step workflow was one of the strongest patterns we measured. A well-written workflow can move the agent from unable to complete a task to producing a correct solution on the first try.
+
+One example from our codebase: a six-step workflow for deploying a new integration. The agent followed it step by step. The share of PRs with missing wiring files dropped from 40% to 10%, and the agent finished faster on average. Correctness went up 25%. Completeness went up 20%.
+
+For complex workflows, keep the main file concise and use reference files for branching cases.
+
+### 3. Decision tables resolve ambiguity before the agent writes code
+
+When your codebase has two or three reasonable ways to do something, decision tables force the choice up front. This is the pattern that most directly improved adherence to codebase conventions.
+
+Example: resolving React Query vs Zustand for state management. PRs in this area scored 25% higher on best_practices. The table resolved the ambiguity before the agent wrote a single line of code.
+
+### 4. Examples from the real codebase improve code reuse
+
+Short snippets of 3–10 lines from actual production code improved reuse and pattern adherence. Keep it to a few examples that are most relevant and not duplicative. More than that and the agent starts pattern-matching on the wrong thing.
+
+### 5. Domain-specific rules still matter
+
+This is the pattern most people already associate with AGENTS.md: language- or org-specific gotchas. This works when the rule is specific and enforceable. It stops working when you stack dozens of them.
+
+### 6. Pair every "don't" with a "do"
+
+Warning-only documentation consistently underperformed documentation that paired prohibitions with a concrete alternative.
+
+If you add *Don't instantiate HTTP clients directly*, pair it with *Use the shared apiClient from lib/http with the retry middleware*.
+
+The first on its own makes the agent cautious and exploratory. The pair tells it what to do and moves on.
+
+AGENTS.md files with 15+ sequential "don'ts" and no "dos" caused the agent to over-explore, stay conservative, and do less work.
+
+### 7. Keep your code modular, and AGENTS.md too
+
+The best-performing agent docs described relatively isolated submodules. Mid-size modules, around 100 core files, with a 100–150 line AGENTS.md and a few reference documents, were where we saw the 10–15% cross-metric gains. Examples: UI components of the client, standalone services.
+
+Huge, cross-cutting AGENTS.md files at the repo root underperformed module-level ones. But the document itself is only part of the story.
+
+In our study, the worst-performing AGENTS.md files were the ones sitting on top of massive surrounding documentation. One module had 37 related docs totaling about 500K characters. Another had 226 docs totaling over 2MB. In both cases, removing just the AGENTS.md barely changed agent behavior. The agent kept finding and reading the surrounding doc sprawl, and the sprawl was the problem.
+
+If your AGENTS.md is good but your module has 500K of specs around it, the specs are what the agent is reading. Fix the documentation environment, not just the entry point.
+
+## Where AGENTS.md falls short
+
+### The overexploration trap
+
+This is the most common failure mode we observed, and it's essentially context rot.
+
+Two patterns cause it:
+
+**1. Too much architecture overview.**
+
+The agent gets pulled into reading documentation files, sometimes dozens of them, trying to "better understand the architecture." It loads tens or hundreds of thousands of tokens of context, and the output gets worse.
+
+**2. Excessive warnings**
+
+A big section of "don'ts" without matching "dos" produces a specific failure. The agent reads each instruction, tries to figure out whether it applies to the current task, and starts verifying its solution against every single warning. With 30–50 warnings, that means reading migration scripts, checking API version compatibility, and exploring auth middleware code, even on a task where none of it matters.
+
+### New patterns break old documentation
+
+If you're introducing a pattern that doesn't exist in your codebase yet, AGENTS.md can actively steer the agent in the wrong direction.
+
+### Know what you're optimizing for
+
+Different patterns move different metrics. Pick the patterns that target the problem you actually have.
+
+## How agents actually find your docs
+
+Before deciding how to migrate your existing documentation, it helps to know what the agent actually reads. We traced documentation discovery across hundreds of sessions. The discovery rates are lopsided enough to shape migration priorities.
+
+| Discovery method | Rate |
+|---|---|
+| AGENTS.md (auto-loaded from hierarchy) | 100% |
+| References out of AGENTS.md (on demand) | 90%+ |
+| Directory-level README.md (when working in that dir) | 80%+ |
+| Nested READMEs in subdirectories not being worked in | ~40% |
+| Orphan docs in _docs/ folders with no references | <10% |
+
+AGENTS.md is the only documentation location with reliable discovery. If something needs to be seen, it either lives there or is directly referenced from there. Moving the content into a referenced location is usually higher leverage than writing more docs.
+
+## Migrating existing docs
+
+Every company already has READMEs, architecture docs, and design specs scattered across the repo. Here's how to turn that into something an agent can actually use.
+
+**Should you just rename your README.md to AGENTS.md?**
+
+READMEs and AGENTS.md serve different audiences, but they can be reused. Agents are good enough at codebase summarization now that human-oriented docs are less necessary than they used to be. You can either write an agentic doc from scratch, or reuse your README. If you reuse it, trim it aggressively. Keep it short, follow the patterns above, and cut any section that's there for humans to skim.
+
+**When to keep existing documentation**
+
+If the docs are high quality, current, to the point, and have examples, reuse them. Reference them from module- or folder-level AGENTS.md files. Don't put more than 10–15 references in a single AGENTS.md and keep the context lean. And audit the surrounding environment: if the module around your AGENTS.md has dozens of architecture docs and spec files, the agent will find and read them whether you reference them or not. A focused 150-line AGENTS.md sitting on top of 500K of surrounding specs won't save the agent from the specs.
+
+**AGENTS.md isn't the only path**
+
+Agents find reference material through grep and semantic search too. About half of all search-result hits in our traces came from those tools, not from AGENTS.md references. If you're keeping legacy documentation, make sure the docs include relevant code examples and descriptive text that's searchable. A well-structured AGENTS.md gives you more control over what ends up in the context window, but it isn't the only way in.
+
+## What this study didn't cover
+
+We focused on one-shot trajectories and the agent's ability to finish coding tasks without human intervention. We didn't look at best practices for maintaining AGENTS.md over time, though we're exploring that now. We also didn't cover operational, interactive, or analytics tasks. Those are coming in future posts.

package/events/README.md

@@ -0,0 +1,89 @@
+# Deft Events
+
+Unified structural artifact listing every framework event in a single data
+file, partitioned by the required `category` enum.
+Wired under epic [#635](https://github.com/deftai/directive/issues/635) per
+the canonical [#642 workflow comment](https://github.com/deftai/directive/issues/642#issuecomment-4330742436)
+and unified per the Repair Authority [AXIOM] proposal
+([#709](https://github.com/deftai/directive/issues/709)) and the
+data-file-convention check follow-up
+([#710](https://github.com/deftai/directive/issues/710)). The prior
+`events/behavioral.yaml` registry has been folded into `registry.json`.
+
+## Files
+
+- `registry.json` — single source of truth for every event name, category,
+  payload contract, detector / emission pointer, and consumer pointers.
+  Lists 5 `detection-bound` events and 4 `behavioral` events (9 total).
+- `registry.schema.json` — schema validating the registry's shape, including
+  the required `category` enum (`detection-bound` | `behavioral`).
+- `event-record.schema.json` — schema for individual emitted event records.
+
+## Categories
+
+Every entry MUST carry a `category` enum value. Two categories exist today;
+future categories are additive enum extensions per the
+data-file-convention check ([#710](https://github.com/deftai/directive/issues/710)):
+
+- **`detection-bound`** — detectable from filesystem state alone (e.g. dirty
+  tree, vBRIEF schema invalidity, version drift). Emitted via
+  `scripts/_event_detect.py`. Detector lives at the call site documented in
+  the entry's `trigger` field.
+- **`behavioral`** — requires runtime instrumentation (paired
+  `session:interrupted` / `session:resumed`, `plan:approved`,
+  `legacy:detected`). Emitted via `scripts/_events.py`, which manages 1:1
+  session-pair invariants and a JSONL append-only log at
+  `<project_root>/.deft-cache/events.jsonl`.
+
+## Emission
+
+Both helpers consume the same `registry.json` data file and produce records
+conforming to `event-record.schema.json`:
+
+```json
+{
+  "event": "<registered name>",
+  "detected_at": "<UTC ISO-8601 seconds>",
+  "payload": { ...per-event contract... }
+}
+```
+
+`scripts/_event_detect.py::emit(name, payload)` validates against the full
+registry (any registered name is accepted) and is silent by default; when the
+`DEFT_EVENT_LOG` environment variable points to a writable path, each
+emission is appended as a single JSON line.
+
+`scripts/_events.py::emit(name, payload)` validates against the
+`category="behavioral"` subset of the registry, generates a sortable event id
+for pairing semantics, enforces required-payload contracts, and persists to
+`<project_root>/.deft-cache/events.jsonl` (or a path injected via `log_path` /
+`DEFT_EVENT_LOG`). The log lives under the already-gitignored `.deft-cache/`
+rather than `.deft/`, which is no longer blanket-gitignored now that
+`.deft/core/` is a committed payload (#11 / #1465). Use this helper when
+emitting behavioral events from
+skills (`python -m scripts._events emit ...`).
+
+## Adding an event
+
+1. Append the entry to `registry.json` with the appropriate `category`,
+   payload contract, trigger pointer, and consumer pointers (validate via
+   `tests/cli/test_events.py` and `tests/cli/test_behavioral_events.py`).
+2. Add the detection / emission call site in `scripts/` or the relevant
+   surface (use `scripts/_event_detect.py` for detection-bound,
+   `scripts/_events.py` for behavioral).
+3. Reference the event by name from at least one consumer (skill, task,
+   script) so the surface stays usable -- the schema requires `consumers`
+   to be a non-empty array.
+
+The registry's `consumers` array is the single audit trail for who reacts
+to each event — keep it current when wiring or removing call sites.
+
+## Adding a new category
+
+New categories are an additive change to the schema's `category` enum:
+update `registry.schema.json` `$defs.Event.properties.category.enum`,
+document the new category in the registry `description` and this README,
+and add corresponding tests asserting the new category is recognized.
+The existing 5 detection-bound + 4 behavioral entries remain stable
+through such extensions per the unification convention agreed in #642 /
+#709 / #710.

package/events/event-record.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/deftai/directive/events/event-record.schema.json",
+  "title": "Deft Event Record",
+  "description": "Schema for a single emitted event record produced by scripts/_event_detect.py::emit() (filename is intentionally distinct from the sibling vBRIEF's scripts/_events.py for behavioral events; merge-time consolidation may unify them). The shape is uniform across detection-bound and behavioral events; the per-event payload contract is defined in events/registry.json.",
+  "type": "object",
+  "required": ["event", "detected_at", "payload"],
+  "additionalProperties": false,
+  "properties": {
+    "event": {
+      "type": "string",
+      "description": "Canonical event name; MUST match an entry in events/registry.json.",
+      "pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)+$"
+    },
+    "detected_at": {
+      "type": "string",
+      "description": "UTC ISO-8601 timestamp (seconds precision) when emit() was called. Format: YYYY-MM-DDTHH:MM:SSZ.",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    },
+    "payload": {
+      "type": "object",
+      "description": "Per-event payload object. Keys/types defined in events/registry.json under the matching event's payload contract.",
+      "additionalProperties": true
+    }
+  }
+}