Skip to content

getting-started.md

Latest commit

 

History

History
89 lines (53 loc) · 6.38 KB

getting-started.md

File metadata and controls

89 lines (53 loc) · 6.38 KB

Getting Started with Deft Directive

Deft Directive is a Markdown framework that provides layered behavioral rules, workflow strategies, and quality gates for AI-assisted software development. This guide walks you through installing Deft, configuring your preferences, creating your first project specification, and using strategies to drive implementation.

Note: Full guide content is deferred until Phases 1-3 of the Deft Directive specification ship. This stub establishes the document structure; sections will be fleshed out as the framework stabilises. See SPECIFICATION.md and ROADMAP.md for current status.

Prerequisites

Installation

First Project

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 for the recurring symptom). Scope the first populate so it lands in seconds rather than minutes:

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 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; the canonical agent-facing description of the workflow lives in skills/deft-directive-refinement/SKILL.md Phase 0.

Using Strategies

Agent Configuration