@deftai/directive-content 0.55.0

package/tools/RWLDL.md

@@ -0,0 +1,80 @@
+# Ralph Wiggum's Loop-de-Loop (RWLDL)
+
+Iterative code refinement by alternating micro (detailed) and macro (high-level) improvements.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [taskfile.md](./taskfile.md) | [../coding/coding.md](../coding/coding.md) | [../coding/testing.md](../coding/testing.md)
+
+## Overview
+
+- ! Perform up to **N** full Loop-de-Loops (LDLs); N is configurable (default: 5)
+- ! Stop early if no meaningful improvements (>5% impact on perf, coverage, or complexity) are found in two consecutive evaluation steps (1 or 3)
+- ! Stop early if all verification criteria are met
+- ! Track state in `ldl-progress.md`
+
+## Loop-de-Loop Steps
+
+### Step 1 — Micro Review (Close-Up Scrutiny)
+
+- ! Read current state: `ldl-progress.md`, recent git commits, test results, logs
+- ! Examine code granularly for:
+  - Comments and readability
+  - Code quality (naming, style)
+  - DRY violations
+  - Micro-performance (e.g., loop optimizations)
+  - Testing gaps
+- ~ Quantify with tools (lint scores, complexity metrics)
+- ! List 2–5 prioritized fixes, each atomic (<100 LOC change)
+- ? If none found, note and proceed to Step 5 (verification)
+
+### Step 2 — Micro Implement & Test
+
+- ! For each fix from Step 1, implement in small steps
+- ! Self-critique: list 3 downsides; mitigate top 2
+- ! Run before committing:
+  - Unit and integration tests
+  - Fuzzing / property-based tests
+  - Lint and type checks
+  - Performance profiles
+- ! Fix all failures before committing
+- ! Git commit with descriptive message
+- ! Update `ldl-progress.md` with summary, metrics deltas, and completed checkboxes
+
+### Step 3 — Macro Review (5,000-Foot View)
+
+- ! Reset perspective — ignore micro details
+- ! Evaluate holistically for:
+  - Speed and scalability (Big O, parallelism)
+  - Modularity (SOLID, separation of concerns)
+  - Broader DRY and reliability (error handling, redundancy)
+  - Security and performance at scale
+- ~ Check externalities: dependencies, docs, APIs
+- ! List 1–3 high-impact changes; quantify potential gains
+- ? If none found, note and proceed to Step 5 (verification)
+
+### Step 4 — Macro Implement & Test
+
+- ! Same process as Step 2, but for Step 3 changes
+- ! Additionally include:
+  - Security scans (e.g., SAST)
+  - End-to-end tests
+- ! Commit and update `ldl-progress.md`
+
+### Step 5 — Loop or Verify
+
+- If improvements were made → return to Step 1 for next LDL
+- Otherwise, verify:
+  - ! All tests pass (coverage ≥95%)
+  - ! No lint or security issues
+  - ! Benchmarks stable
+  - ! README and docs current
+- If verified → output **COMPLETE**
+- Else → **CONTINUE** to next LDL
+
+## Progress Tracking
+
+- ! After each LDL, append to `ldl-progress.md`:
+  - LDL count
+  - Key metrics (coverage, complexity, perf)
+  - Rationale for continuing or stopping

package/tools/greptile.md

@@ -0,0 +1,141 @@
+# Greptile Integration
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [deft-directive-review-cycle skill](../skills/deft-directive-review-cycle/SKILL.md) | [Greptile docs](https://greptile.com/docs)
+
+**Scope:** Configuring the Greptile AI code review bot for use with deft projects.
+
+## Overview
+
+Greptile reviews pull requests with full codebase context. When used with deft, it integrates with the `deft-directive-review-cycle` skill to enable automated review/fix loops.
+
+## Recommended Dashboard Settings (org-wide)
+
+! Configure these in the [Greptile dashboard](https://app.greptile.com/review/github) as organization defaults — they apply to all repos and avoid per-repo duplication.
+
+### Review Triggers
+
+- ! `triggerOnUpdates` ("Automatically trigger on new commits") → **on** — re-reviews on every push so the review-cycle loop can reach its exit condition
+- ? `triggerOnDrafts` ("Review draft pull requests") → on if you want early feedback on draft PRs
+
+### Status
+
+- ! `statusCheck` ("Create a status check for each PR") → **on** — posts a `"Greptile Review"` check run that org rulesets can require
+- ~ `statusCommentsEnabled` ("Enable status comments") → **on**
+
+### Comments
+
+- ~ `strictness` → **2** (balanced) — 1 is verbose, 3 is critical-only
+- ~ `commentTypes` → **Syntax, Logic** enabled, **Style** disabled — deft has its own style conventions via RFC 2119 rules
+- ~ `fixWithAI` ("Fix with AI Prompt") → **on** — helps agents understand suggested fixes
+
+### PR Summary
+
+- ! Confidence Score → **on** — the review-cycle skill uses this for its exit condition (must be >3)
+- ~ PR Summary → **on**
+- ~ Issues Table → **on**
+- ? Diagram → optional (adds visual but increases review size)
+- ~ Comments Outside Diff → **on** — the review-cycle skill fetches these explicitly
+
+### Author Exclusions
+
+- ~ Exclude `dependabot[bot]` and `renovate[bot]` — avoids noisy reviews on automated PRs
+
+## Per-Repo Configuration (optional)
+
+Dashboard settings cover most needs. Per-repo `.greptile/` folders are only needed for repo-specific overrides.
+
+### When to use `.greptile/`
+
+- ? `config.json` — override org defaults for a specific repo (e.g. different strictness for a high-risk service)
+- ~ `rules.md` — repo-specific review rules in prose (additive with org rules). SHOULD be present in every repo to give Greptile project-specific context.
+- ? `files.json` — point Greptile at repo-specific context docs (architecture docs, API specs, schemas)
+
+### Starter `.greptile/rules.md` Template
+
+~ Every repo using Greptile SHOULD include a `.greptile/rules.md` with at least the following sections. Adapt the content to your project.
+
+```markdown
+# Review Rules
+
+## Project Context
+- This project uses [brief tech stack description].
+- Primary language(s): [languages].
+
+## Conventions
+- Commit messages follow Conventional Commits: type(scope): description.
+- All files use UTF-8 without BOM.
+- RFC2119 enforcement markers (!, ~, ⊗) are used for rules.
+
+## Review Focus
+- Flag any TODO/FIXME/HACK comments in new code.
+- Verify error handling is present (no silent failures).
+- Check that new public APIs have documentation.
+
+## Ignore
+- Do not flag style issues in generated files.
+- Do not flag line length in markdown files.
+```
+
+### Configuration hierarchy (highest → lowest precedence)
+
+1. Org enforced rules (dashboard — cannot be overridden)
+2. `.greptile/` folder (per-repo, recommended format)
+3. `greptile.json` in repo root (legacy format, still supported)
+4. Dashboard settings (org defaults)
+
+~ Use `.greptile/` over `greptile.json` — it supports cascading, per-directory overrides, structured rules with severity, and `rules.md` prose.
+
+⊗ Duplicate behavioral settings (`triggerOnUpdates`, `statusCheck`, etc.) in per-repo configs when they match the org defaults — maintain them in one place.
+
+## Check Runs vs. Commit Statuses
+
+! Greptile posts **check runs** (GitHub Checks API), not **commit statuses** (Statuses API). This distinction matters when verifying or debugging the integration.
+
+To verify Greptile posted a check run on a commit:
+
+```
+gh api repos/<owner>/<repo>/commits/<sha>/check-runs --jq '.check_runs[] | select(.name == "Greptile Review")'
+```
+
+⊗ Use `commits/<sha>/statuses` to look for Greptile — that endpoint will always be empty for Greptile.
+
+The check run name is `"Greptile Review"` — this must match the context name in any org ruleset or branch protection rule that requires it.
+
+## Troubleshooting
+
+### Greptile reviews PRs but no check run appears
+
+1. Verify `statusCheck` is enabled in the dashboard
+2. Verify the repo is in the Enabled list on the Repositories tab
+3. Check the GitHub App permissions — needs R/W for `checks` and `commit statuses`
+4. Use the Checks API (not Statuses API) to verify: `gh api repos/<owner>/<repo>/commits/<sha>/check-runs`
+5. If all settings are correct and check runs still don't appear, contact Greptile support — this may be a repo-specific issue on their end
+
+### Greptile doesn't re-review after pushing fixes
+
+1. Verify `triggerOnUpdates` is enabled in the dashboard
+2. Re-reviews may have a delay (~3-5 minutes vs. near-instant for initial reviews)
+3. As a fallback, comment `@greptileai` on the PR to manually trigger a re-review
+4. Greptile edits its existing summary comment in place — check the `Last reviewed commit` field and `updated_at` timestamp
+
+### Review-cycle loop never exits
+
+1. Check the `deft-directive-review-cycle` skill's Pre-Flight Check section
+2. Verify `triggerOnUpdates` is enabled — without it, Greptile never produces a follow-up review
+3. Verify the confidence score section is enabled in dashboard settings — the exit condition requires confidence >3
+
+## Anti-Patterns
+
+- ⊗ Maintain identical Greptile settings in per-repo configs across multiple repos — use dashboard org defaults
+- ⊗ Use `commits/<sha>/statuses` to check for Greptile — use `commits/<sha>/check-runs`
+- ⊗ Enter the review-cycle loop without verifying `triggerOnUpdates` is enabled
+- ⊗ Assume Greptile re-reviews instantly — allow 3-5 minutes before falling back to `@greptileai`
+
+## References
+
+- Greptile docs: https://greptile.com/docs
+- `.greptile/` config reference: https://greptile.com/docs/code-review/greptile-config-reference
+- `greptile.json` reference: https://greptile.com/docs/code-review/greptile-json-reference
+- PR trigger configuration: https://greptile.com/docs/code-review-bot/trigger-code-review

package/tools/installer.md

@@ -0,0 +1,23 @@
+# Installer
+
+Legend: !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## Version Currency
+
+! `deft-install` MUST query the GitHub Releases API (`GET /repos/deftai/directive/releases/latest`) after the welcome banner and before the project-name prompt, with a 1.5s combined connect/read timeout. The `User-Agent` header MUST be `deft-install/<version>`.
+
+! On version match, `deft-install` MUST print a one-line confirmation (`Running latest (<version>)`) and proceed without prompting.
+
+! On version mismatch, `deft-install` MUST print the embedded version, latest version, publish date, and download URL, then prompt `[y/N]` with default abort.
+
+! On network error or timeout, `deft-install` MUST print a "could not verify" message and prompt `[y/N]` with default abort.
+
+! On non-TTY stdin, `deft-install` MUST exit 1 for any non-match outcome unless `DEFT_NO_UPDATE_CHECK=1` is set or `--no-update-check` is passed.
+
+⊗ Run the version check for `--version` or `--help` invocations.
+
+⊗ Suppress the prompt for any class of drift: rc-vs-GA, patch, and minor drift all use the same confirmation rule.
+
+⊗ Warn when the embedded version is ahead of latest. Locally built development binaries must proceed without update-check noise in that case.
+
+Comparison rule: warn iff `embedded < latest` under SemVer ordering. Pre-release identifiers sort below their corresponding GA per SemVer, so `v0.20.0-rc.1 < v0.20.0` without special-casing release candidates.

package/tools/taskfile-migration.md

@@ -0,0 +1,32 @@
+# Taskfile Migration Guide
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [taskfile.md](./taskfile.md) | [main.md](../../main.md)
+
+## When to Migrate
+
+- ~ Migrate from Makefiles or shell scripts when the project adopts Deft
+- ~ Migrate when build automation becomes complex enough to benefit from Task's dependency resolution and caching
+- ? Skip migration for trivial scripts that are rarely changed
+
+## Migration Steps
+
+1. **Audit** -- List all existing build/test/deploy commands (Makefile targets, npm scripts, shell scripts)
+2. **Map** -- Map each command to a Task equivalent using [taskfile.md](./taskfile.md) naming conventions
+3. **Create** -- Write `Taskfile.yml` with mapped tasks; use `deps` for ordering, `sources`/`generates` for caching
+4. **Verify** -- Run each task and compare output to the original command
+5. **Remove** -- Delete or archive the old Makefile/scripts once all tasks are verified
+
+## Common Migrations
+
+- `make build` -> `task build`
+- `npm run test` -> `task test`
+- `./scripts/deploy.sh` -> `task deploy`
+- `make lint && make test` -> `task check` (with deps: [lint, test])
+
+## Anti-Patterns
+
+- ⊗ Migrating and keeping the old system active (causes confusion about which to use)
+- ⊗ Translating complex shell logic directly into Task `cmds` -- extract to scripts instead
+- ≉ Migrating all scripts at once without verifying each individually

package/tools/taskfile.md

@@ -0,0 +1,185 @@
+# Taskfile Guidelines
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [main.md](../../main.md) | [taskfile-migration.md](./taskfile-migration.md)
+
+**Scope:** Task-based build automation using [Task](https://taskfile.dev/) instead of Makefiles or shell scripts.
+
+## Task-Centric Workflow
+
+- ! Use `task` for repeatable operations
+- ! Add tasks instead of standalone shell scripts
+- ! Define default task: `task --list`
+- ⊗ Manual shell scripts for repeatable workflows
+
+## Core Principles
+
+**Entrypoint:**
+- ! Task as single entry for common flows: `task dev`, `task test`, `task build`, `task release`
+- ~ Avoid documenting raw commands in README beyond "install Task, then run X"
+
+**Composability:**
+- ~ Keep tasks small and declarative
+- ~ Move logic to scripts/binaries, Task orchestrates
+- ⊗ Embed complex shell logic in `cmds`
+
+**Structure:**
+- ! Default task shows available tasks (`task --list`)
+- ~ Split large setups: `Taskfile.dev.yml`, `Taskfile.ci.yml`, `Taskfile.tools.yml`
+- ~ Include from root `Taskfile.yml` for readability
+
+## Naming Conventions
+
+**Single-language projects:**
+- ! Use generic names: `fmt`, `lint`, `test`, `build`
+- ! Use clear verbs: `generate`, `deploy`, `publish`, `clean`
+
+**Multi-language projects:**
+- ! Use namespaced names: `py:fmt`, `go:fmt`, `cpp:fmt`, `ts:fmt`
+- ! Provide generic aliases delegating to all languages:
+```yaml
+fmt:
+  deps: [py:fmt, go:fmt]
+lint:
+  deps: [py:lint, go:lint]
+```
+
+**Task namespaces:**
+- ! Group related tasks: `docker:build`, `docker:push`, `db:migrate`, `db:seed`, `app:run`
+
+## Dependencies, Caching, Performance
+
+**Dependencies:**
+- ~ Use `deps` for task ordering/reuse
+- ⊗ Manually sequence tasks in `cmds`
+
+**Caching:**
+- ~ Configure `sources`/`generates` + `method: checksum`
+- ~ Incremental builds like Make-style
+- ~ Only re-run when inputs change
+
+**Idempotency:**
+- ~ Use `status` or `preconditions` for idempotent setup
+- ~ Skip heavy steps if already completed (e.g. "tool installed", "DB running")
+
+## Robustness & Safety
+
+**Shell options:**
+- ! Set `set: [errexit, nounset, pipefail]` on tasks
+- Exits on errors, undefined vars, pipe failures
+
+**Validation:**
+- ~ Use `requires: vars: [VAR]` to fail early
+- Example: `requires: vars: [AWS_PROFILE, VERSION]`
+- ⊗ Let scripts misbehave with missing vars
+
+**Cleanup:**
+- ~ Use `defer` for cleanup (temp files, background processes)
+- ~ Cleanup runs even on task failure
+
+## UX for Teams & CI
+
+**Documentation:**
+- ! Add `desc` for every user-facing task
+- ! `task --list` must be self-documenting CLI
+- ~ Mark internal tasks as `internal: true`
+- ⊗ Expose internal wiring tasks to users
+
+**Variables & Templates:**
+- ~ Use `vars`, `env`, `{{.CLI_ARGS}}`, `{{.USER_WORKING_DIR}}`
+- ~ Support monorepos/multi-service setups cleanly
+- ~ Avoid duplicating similar tasks
+
+**Artifacts:**
+- ~ Keep local/ephemeral artifacts in temp dir
+- ~ Use `TASK_TEMP_DIR` for generated caches/checksums
+- ~ Ignore in VCS or commit for reproducible codegen
+
+## Common Task Commands
+
+```bash
+task fmt                # Format code
+task lint               # Lint code
+task test               # Run tests
+task test:coverage      # Run tests with coverage (! ≥85%)
+task quality            # All quality checks
+task check              # Pre-commit (! run: fmt+lint+type+test)
+task build              # Build project
+```
+
+## Example Taskfile Structure
+
+```yaml
+version: '3'
+
+set: [errexit, nounset, pipefail]
+
+tasks:
+  default:
+    desc: List all tasks
+    cmds:
+      - task --list
+    silent: true
+
+  fmt:
+    desc: Format code
+    sources:
+      - '**/*.py'
+    cmds:
+      - ruff format .
+
+  lint:
+    desc: Lint code
+    sources:
+      - '**/*.py'
+    cmds:
+      - ruff check .
+
+  test:
+    desc: Run tests
+    deps: [fmt, lint]
+    cmds:
+      - pytest
+
+  build:
+    desc: Build project
+    deps: [test]
+    sources:
+      - 'src/**/*.py'
+    generates:
+      - 'dist/*'
+    cmds:
+      - python -m build
+
+  clean:
+    desc: Clean build artifacts
+    cmds:
+      - rm -rf dist/ build/ *.egg-info
+```
+
+## Best Practices
+
+- ! Always include default task
+- ! Use RFC 2119 keywords in task descriptions
+- ~ Keep tasks <20 lines; extract scripts if larger
+- ~ Use `dotenv` for environment files
+- ~ Prefer `cmd` over `sh` for simple commands
+- ⊗ Hardcode paths; use templates
+- ⊗ Silent failures; add error handling
+
+## Anti-Patterns
+
+- ⊗ Shell scripts for repeatable tasks → use Task
+- ⊗ Complex shell in `cmds` → extract to scripts
+- ⊗ Undocumented tasks → add `desc`
+- ⊗ Ignoring `deps` → use for ordering
+- ⊗ No caching config → add `sources`/`generates`
+- ⊗ Exposing internal tasks → mark `internal: true`
+
+## References
+
+- Docs: https://taskfile.dev/
+- Styleguide: https://taskfile.dev/docs/styleguide
+- Installation: https://taskfile.dev/installation/
+- Migration: [taskfile-migration.md](./taskfile-migration.md)