git:20260704.c66dd37 to git:20260830.886ca59

<!-- 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 the **Cold-start bootstrap** block at the top of the project's `README.md` and follow the global-first npm ladder there before any other instruction in this file or in the consumer AGENTS.md. `README.md` is always committed (never gitignored) and does not depend on the `.deft/core/` payload, so the recovery ladder is reachable on a fresh clone even when the vendored payload is absent (#2273).

! 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:

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

```

**Work with existing deft project**:

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` |

## 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.