@deftai/directive-content 0.66.1 → 0.67.0

package/SKILL.md

@@ -0,0 +1,220 @@
+<!-- DEFT-PREAMBLE-V1 -->
+<!--
+! Cold-start check: deft runs from the npm-installed engine (`npm i -g @deftai/directive`). If neither `deft` nor `directive` will run on this machine, do not proceed with the instructions below -- recover first (#1933 Option 1, deprecate-by-disuse).
+! To recover: read `.deft/core/UPGRADING.md`, find the section whose "Applies when" clause matches your symptom, and follow that section verbatim before any other instruction in this file or in the consumer AGENTS.md.
+! Respect any "Restart required" directive -- if present, stop and tell the user to start a fresh session after cleanup commands complete. Otherwise continue.
+-->
+---
+name: deft
+description: Apply deft framework standards for AI-assisted development. Use when starting projects, writing code, running tests, making commits, or when the user references deft, project standards, or coding guidelines.
+user-invocable: false
+metadata:
+  clawdbot:
+    requires:
+      bins: ["task"]
+    homepage: "https://github.com/deftai/directive"
+os: ["darwin", "linux", "windows"]
+---
+
+# Deft Framework
+
+A layered framework for AI-assisted development with consistent standards and workflows.
+
+## When This Skill Activates
+
+This skill automatically loads when you:
+- Start work in a deft-enabled project (has `.deft/core/` directory)
+- Reference deft, project standards, or coding conventions
+- Run tests, make commits, or perform quality checks
+- Ask about project structure, workflows, or best practices
+
+## Missing Config Auto-Setup
+
+! When this skill activates, check for USER.md at the platform-appropriate path
+(Windows: `%APPDATA%\deft\USER.md`, Unix: `~/.config/deft/USER.md`, or `$DEFT_USER_PATH`).
+
+**If USER.md is missing**: Skip everything else in this file. Ask this question immediately
+as your FIRST and ONLY response — no summary, no menu, no preamble:
+
+> Deft has solid opinions on how code should be written and tested — I just need
+> a few things about you and your project. First, how deep do you want to go?
+>
+> 1. **I'm technical — ask me everything**
+> 2. **I have some opinions but keep it simple**
+> 3. **Just pick good defaults — I care about the product, not the tools**
+
+Then continue with `skills/deft-directive-setup/SKILL.md` Phase 1 for remaining questions.
+
+**If USER.md exists but `./vbrief/PROJECT-DEFINITION.vbrief.json` is missing**: Skip to
+`skills/deft-directive-setup/SKILL.md` Phase 2.
+
+**If USER.md and `./vbrief/PROJECT-DEFINITION.vbrief.json` both exist but no scope vBRIEFs in `./vbrief/` lifecycle folders**:
+Skip to `skills/deft-directive-setup/SKILL.md` Phase 3. Start the specification interview
+imediately — ask what to build and features as the first question.
+
+### ⊗ Project Root vs Framework Internals
+
+! When checking for project-level files (`PROJECT-DEFINITION.vbrief.json`, scope vBRIEFs,
+`PRD.md`), ONLY look at `./vbrief/` and its lifecycle subdirectories.
+
+- ! `./vbrief/PROJECT-DEFINITION.vbrief.json` — the user's project config
+- ! `./vbrief/proposed/`, `./vbrief/pending/`, `./vbrief/active/`, `./vbrief/completed/` — scope vBRIEFs in lifecycle folders
+- ⊗ Count ANY file inside `.deft/core/` (canonical) or `./deft/` (legacy pre-v0.27) as a project-level artifact — those are
+  framework-internal (e.g. `.deft/core/PROJECT.md`, `.deft/core/specs/`, `.deft/core/templates/`
+  are all part of the framework, NOT the user's project)
+
+- ⊗ Present a summary of the config and ask what the user wants to do
+- ⊗ Ask "what would you like to do" or "what are we building" — start the interview directly
+- ⊗ Show menus, recaps, or workflow overviews before starting the next missing phase
+
+## Core Principle: Rule Precedence
+
+Deft uses hierarchical rules where more specific overrides general.
+USER.md has two sections with different precedence:
+
+```
+USER.md Personal       ← HIGHEST (name, custom rules — always wins)
+  ↓
+PROJECT-DEFINITION.vbrief.json  ← Project-specific (strategy, coverage, languages, tech stack)
+  ↓
+USER.md Defaults       ← Fallback defaults (used when PROJECT-DEFINITION doesn't specify)
+  ↓
+{language}.md          ← Language standards (python.md, go.md, typescript.md, cpp.md)
+  ↓
+{tool}.md              ← Tool guidelines (taskfile.md, git.md)
+  ↓
+main.md                ← General AI behavior
+  ↓
+scope vBRIEFs          ← LOWEST precedence (requirements in lifecycle folders)
+```
+
+**IMPORTANT**: USER.md `Personal` section always wins. For project-scoped settings
+(strategy, coverage, languages), `PROJECT-DEFINITION.vbrief.json` overrides USER.md `Defaults`.
+
+## File Reading Strategy (Lazy Loading)
+
+**DO NOT** read all deft files at once. Read only what you need:
+
+1. **Always start with**: `.deft/core/main.md` (general guidelines)
+2. **Check for**: `~/.config/deft/USER.md` (personal overrides - highest precedence)
+3. **Check for**: `./vbrief/PROJECT-DEFINITION.vbrief.json` (project-specific rules)
+4. **Then read language-specific** only if working with that language:
+   - `.deft/core/languages/python.md`
+   - `.deft/core/languages/go.md`
+   - `.deft/core/languages/typescript.md`
+   - `.deft/core/languages/cpp.md`
+5. **Read tool files** only when using that tool:
+   - `.deft/core/tools/taskfile.md` (when running tasks)
+   - `.deft/core/scm/git.md` (when using git)
+   - `.deft/core/scm/github.md` (when using GitHub)
+
+## Task-Centric Workflow
+
+Deft projects use **Taskfile** as the universal task runner.
+
+```bash
+task --list        # See all available tasks
+task check         # CRITICAL: Run before EVERY commit
+```
+
+See `.deft/core/tools/taskfile.md` for complete task standards and common commands.
+
+## Development Methodology
+
+**Test-Driven Development (TDD)**:
+1. Write test first → Watch it fail → Implement → Refactor → Repeat
+2. Default: ≥85% coverage (check `project.md` for overrides)
+3. Implementation is INCOMPLETE until tests pass
+
+**Spec-Driven Development (SDD)** for new features/projects:
+1. Run `.deft/core/run spec` — sizing gate selects Light or Full path
+2. Light: Interview → scope vBRIEFs in `vbrief/proposed/` (embedded requirements) → Implement
+3. Full: Interview → rich narratives in `specification.vbrief.json` (approval gate) → scope vBRIEFs → Implement
+
+See `.deft/core/coding/testing.md` for complete testing standards.
+
+## Quality Standards
+
+**Before Every Commit**:
+```bash
+task check  # MUST run: fmt, lint, type check, test, coverage
+```
+
+**Conventional Commits**: Use https://www.conventionalcommits.org/en/v1.0.0/ format
+**File Naming**: Use hyphens (e.g., `user-service.py`), not underscores
+**Secrets**: Store in `secrets/` directory with `.example` templates
+
+See `.deft/core/coding/coding.md` and `.deft/core/scm/git.md` for complete standards.
+
+## Language-Specific Standards
+
+All languages require ≥85% test coverage. See language-specific files:
+- `.deft/core/languages/python.md`
+- `.deft/core/languages/go.md`
+- `.deft/core/languages/typescript.md`
+- `.deft/core/languages/cpp.md`
+
+## New Project Setup
+
+**Initialize new project**:
+```bash
+.deft/core/run init       # Create deft structure
+.deft/core/run bootstrap  # User config (first time only)
+.deft/core/run project    # Project config → vbrief/PROJECT-DEFINITION.vbrief.json
+.deft/core/run spec       # Sizing gate → Light (scope vBRIEFs) or Full (specification.vbrief.json → scope vBRIEFs)
+```
+
+**Work with existing deft project**:
+1. **First time?** If `~/.config/deft/USER.md` doesn't exist, run `.deft/core/run bootstrap`
+2. Read `.deft/core/main.md` (general guidelines)
+3. Read `~/.config/deft/USER.md` (personal preferences - highest precedence)
+4. Read `./vbrief/PROJECT-DEFINITION.vbrief.json` (project rules)
+5. Run `task --list` to see available tasks
+
+See `.deft/core/main.md` for complete workflow details.
+
+## Self-Improvement
+
+Deft learns and evolves via `meta/` directory:
+- `lessons.md` - Patterns learned (AI can update)
+- `ideas.md` - Future improvements
+- `suggestions.md` - Project-specific suggestions
+
+## Platform Integration
+
+This SKILL.md follows the **AgentSkills specification**, compatible with:
+- **Claude Code**: `~/.claude/skills/deft/` or `.claude/skills/deft/`
+- **clawd.bot**: `~/.clawdbot/skills/deft/` or install via `clawdhub sync deft`
+- **Warp AI**: Upload to Warp Drive, reference in `WARP.md`/`AGENTS.md`
+
+See `.deft/core/docs/claude-code-integration.md` for integration details.
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| List tasks | `task` or `task --list` |
+| Pre-commit checks | `task check` |
+| Run tests | `task test` |
+| Check coverage | `task test:coverage` |
+| Format code | `task fmt` |
+| Lint code | `task lint` |
+| Initialize deft | `.deft/core/run init` |
+| Configure user | `.deft/core/run bootstrap` |
+| Configure project | `.deft/core/run project` |
+| Generate spec | `.deft/core/run spec` |
+
+## Remember
+
+1. **Lazy load files** - Only read what you need
+2. **User.md Personal is king** - Personal section always wins; Defaults are fallback
+3. **Task-centric** - Use `task` for everything
+4. **Test first** - Write tests before implementation
+5. **Always check** - Run `task check` before commits
+6. **Conventional commits** - Follow the standard
+7. **Coverage matters** - ≥85% by default
+8. **Never lie** - Don't claim checks passed without running them
+
+---
+
+For more details, read the specific files in `.deft/core/` as needed. Start with `main.md` and follow the precedence hierarchy.

package/Taskfile.yml

@@ -345,6 +345,7 @@ tasks:
       - verify:stubs
       - verify:links
       - verify:rule-ownership
+      - verify:biome-config
       - verify:content-manifest
       - verify:contract-drift
       - verify:cursor-tier1
@@ -360,6 +361,7 @@ tasks:
       - verify:cache-fresh
       - verify:pack-drift
       - verify-wip-cap-framework-self-check
+      - verify:agents-md-budget
       - vbrief:validate
       - codebase:validate-structure
       - verify:codebase-map-fresh
@@ -479,7 +481,7 @@ tasks:
   # in ``tasks/framework.yml`` now prints a redaction notice pointing
   # the operator at this surface.
   doctor:
-    desc: "Canonical doctor surface (#1272) -- task doctor [-- --session | --fix | --json | --quiet]. Uses vendored bin.js in source checkouts or global deft on npm consumer deposits (#2022 Phase 3)."
+    desc: "Canonical doctor surface (#1272) -- task doctor [-- --session | --fix | --json | --quiet | --network]. Uses vendored bin.js in source checkouts or global deft on npm consumer deposits (#2022 Phase 3). --network is required to run the payload-staleness check (git remote, then npm registry fallback); it is offline (skipped) by default and discloses the tool + registry class before contacting either (#2182)."
     dir: '{{.USER_WORKING_DIR}}'
     cmds:
       - task: engine:invoke

package/UPGRADING.md

@@ -56,6 +56,26 @@ deft migrate:xbrief
 
 (or `task migrate:xbrief` from a maintainer checkout). The command requires a clean working tree unless you pass `--force`. Legacy `vbrief/` paths and `x-vbrief/` tokens remain **read-accepted** until this migration runs; `deft update` may signpost the same guidance on non-patch upgrades.
 
+Post-migration behavior check (#2149): on xbrief-only projects (`vbrief/` removed), `task issue:ingest -- <N>` now emits `xbrief/proposed/*.xbrief.json` with `xBRIEFInfo.version` from `xbrief/PROJECT-DEFINITION.xbrief.json` (fallback `0.8`), while legacy `vbrief/` projects keep `.vbrief.json` + `vBRIEFInfo.version: "0.6"` until migrated. `task project:render` / `project-render` also stays on `xbrief/PROJECT-DEFINITION.xbrief.json` and no longer recreates `vbrief/` in migrated trees.
+
+### AGENTS.md: managed vs unmanaged header (#2154)
+
+`migrate:xbrief` touches your `AGENTS.md` in two distinct regions:
+
+- **Managed section** (between the `<!-- deft:managed-section ... -->` / `<!-- /deft:managed-section -->` markers): regenerated wholesale by `agents:refresh`, so it always reflects the current framework layout. This region is rendered from the framework template — do not hand-edit it.
+- **Unmanaged header/tail** (everything outside those markers — your project-specific `Session orientation`, `Lifecycle` examples, `Local dev` notes): preserved verbatim across upgrades so your consumer notes survive. Because it is preserved, a rename migration would otherwise leave stale `vbrief/` path literals here. `migrate:xbrief` now applies a **bounded, idempotent** rewrite over the unmanaged region only, replacing the known crossover tokens (`vbrief/` → `xbrief/`, `*.vbrief.json` → `*.xbrief.json`, `vbrief:preflight` → `xbrief:preflight`) while leaving freeform prose untouched. It prints a summary of the replacements.
+
+If you upgraded before this fix landed and your header still points at `vbrief/`, `deft doctor` now emits an `AGENTS.md header drift:` signpost. Re-run `deft migrate:xbrief` (idempotent) to patch the header, or hand-edit the offending path literals.
+
+**Option A (canonical, #2065):** new installs scaffold a **bounded** unmanaged header only — a project one-liner plus a **Session orientation** pointer at the canonical sources below. Do **not** add freeform `Status`, `Next:`, or `Known Issues` blocks; they are retired because the framework preserves the header verbatim while `deft doctor` only checks the managed section (#794, #1308). Session orientation comes from:
+
+- `xbrief/PROJECT-DEFINITION.xbrief.json` (project identity)
+- `xbrief/` lifecycle folders (scoped work)
+- `deft triage:queue` / `deft triage:welcome` (ranked queue)
+- GitHub issues (tracked bugs)
+
+If your header still carries `Status` / `Known Issues` from an older handoff, replace them with the Session orientation pointer (reference implementation: [deftai/cartograph#75](https://github.com/deftai/cartograph/pull/75)). Ephemeral shell quirks MAY stay under a `Local dev` heading only.
+
 ## Public contract layer — `@deftai/directive-types` (#1799)
 
 Downstream TypeScript projects can import the canonical xBRIEF/policy contract instead of hand-mirroring JSON shapes:

package/docs/agent-docs.md

@@ -0,0 +1,44 @@
+# Authoring agent docs (AGENTS.md) for a project
+
+Guidance for structuring the AGENTS.md (and its reference docs) of a project directive creates or maintains. Unlike most style advice, the patterns here are **empirically measured**, not opinion: Augment Code's April 2026 AuggieBench study ran real PRs with and without each pattern and scored the agent's output against the human-reviewed golden PR. Full write-up: [good-agents-md.md](./good-agents-md.md).
+
+Legend (RFC2119): `!`=MUST, `~`=SHOULD, `≉`=SHOULD NOT, `⊗`=MUST NOT, `?`=MAY.
+
+> The headline finding: a good AGENTS.md gave the agent a quality jump equivalent to a model upgrade; a bad one made output **worse than no AGENTS.md at all**. The same file boosted `best_practices` +25% on a routine bug fix and dropped `completeness` -30% on a complex feature in the same module. Structure is the difference.
+
+## The pattern (what the study measured)
+
+| Pattern | Measured effect |
+|---|---|
+| 100–150 line main file + a handful of focused reference files | Top performers; **10–15%** improvement across all metrics in mid-size modules. Gains **reverse** once the main file grows past ~150 lines. |
+| Numbered procedural workflows for multi-step tasks | Missing-wiring PRs **40% → 10%**; correctness **+25%**, completeness **+20%**. |
+| Decision tables for common ambiguities (2–3 reasonable options) | **+25%** best-practices adherence — resolves the choice before the agent writes a line. |
+| 3–10 line snippets from the **real** codebase | Improved reuse and pattern adherence. More than a few, and the agent pattern-matches on the wrong thing. |
+| Paired don't/do rules | Warning-only docs underperform; **15+ unpaired don'ts** measurably cause overexploration. |
+| Module-level files over a root cross-cutting file | Root-level cross-cutting AGENTS.md underperforms module-scoped files. |
+
+## How to structure a project's AGENTS.md
+
+1. ! Keep the always-loaded AGENTS.md to **~100–150 lines**. It is a map (what exists, where to look, the few load-bearing rules), not a manual.
+2. ! Push detail into **focused reference files** the agent loads on demand, each with a clear "load when…" scope. See the reference-chain contract below.
+3. ~ Express multi-step tasks (deploy an integration, add a migration, wire a new endpoint) as **numbered workflows**, not prose. Keep branching cases in reference files.
+4. ~ For each recurring "which of these two approaches?" ambiguity, add a **decision table** that forces the choice up front.
+5. ~ Include a few **short, real** code snippets (3–10 lines) for the patterns you most want reused. Do not paste large or duplicative examples.
+6. ! Write rules as **paired don't/do**, not lone warnings — an unpaired "don't" leaves the agent to guess the "do", and a pile of them triggers overexploration.
+7. ~ Prefer **module-level** agent docs (scoped to the package/app the agent is working in) over one root file that tries to cover everything.
+
+## The reference-chain contract
+
+The discovery-rate principle that governs *what to reference* is named in `REFERENCES.md` ("The reference-chain contract", #644) — read it there rather than duplicating it here. In one line: **if a rule must be followed, it must be reachable in the reference chain; orphan docs (<10% discovery) are effectively invisible, and reachable-but-unreferenced docs are still found and still cost context.**
+
+## The overexploration trap (measured failure modes, not style)
+
+These are the specific blocks the study measured *hurting* agent quality — treat them as defects, not taste:
+
+- ⊗ Do **not** add an "architecture overview" / broad-context section to an always-loaded agent file. On complex tasks it pulls the agent into the reference section to verify its approach against every guideline, producing unnecessary abstractions and incomplete solutions (the measured -30% completeness case).
+- ⊗ Do **not** accumulate 15+ unpaired warnings. Past that threshold the agent over-explores instead of acting.
+- ≉ Avoid stacking dozens of domain-specific gotchas. Domain rules help when specific and enforceable; they stop helping when piled up. Prefer a deterministic gate over prose where one exists (the gate is platform-correct by construction and travels with the repo).
+
+## Relationship to directive's own dogfooding
+
+Directive holds its own AGENTS.md to this bar via the `verify:agents-md-budget` ratchet (#645) and the consumer-side advisory signal (`agentsMdAdvisory`, #2155). The doc-sprawl awareness step in the `deft-directive-sync` skill (#647) surfaces reachable-doc-volume drift before it silently degrades agent quality. This doc is the "how to structure it well" companion to those "keep it from bloating" guards.