RFC: External Directive workspace mode for unvendored GitHub repos

[MScottAdams]

Motivation

Directive currently assumes the project being worked on can host Directive artifacts such as .deft/core/, AGENTS.md, vbrief/, cache state, and project definition files. That works for repos that choose to vendor or install Directive, but it blocks an important workflow:

I want to use Directive to reason about, plan, triage, and manage vBRIEF lifecycle work for a GitHub repo that has not vendored Directive and may never do so.

This matters especially for open source repos where I may not have maintainer rights, do not want to open a scaffolding PR just to use Directive, or want to keep planning state private until it is ready to become an upstream issue or PR.

This also connects to the npm/package direction in #11 and the TypeScript migration RFC #1530. If Directive becomes available through npm or another package manager, the CLI should be useful against repos that do not already contain Directive files.

Proposal

Add an external workspace mode to Directive.

In this mode, Directive separates:

• Target repo: the GitHub repository being analyzed or worked on.
• Directive workspace: a separate local directory or user-owned repo where Directive artifacts live.

The target repo remains clean. Directive reads it for facts, source files, issues, commits, and repository metadata, but writes vBRIEF and Directive state into the external workspace unless the user explicitly asks to export or propose changes upstream.

Example workspace layout:

directive-workspace/
  repos/
    github.com/
      deftai/
        directive/
          PROJECT-DEFINITION.vbrief.json
          vbrief/
            proposed/
            pending/
            active/
            completed/
            cancelled/
          .deft-cache/
          notes/
      some-org/
        some-open-source-repo/
          PROJECT-DEFINITION.vbrief.json
          vbrief/
          .deft-cache/

Desired User Experience

A user should be able to run something like:

deft workspace init ~/directive-workspace
deft workspace attach https://github.com/some-org/some-repo --workspace ~/directive-workspace
deft status --target https://github.com/some-org/some-repo --workspace ~/directive-workspace
deft triage issue 123 --target https://github.com/some-org/some-repo --workspace ~/directive-workspace

Possible npm-oriented usage:

npx @deftai/directive workspace attach https://github.com/some-org/some-repo

Directive should infer the workspace when possible, but the boundary must stay explicit in diagnostics:

• "Reading target repo: some-org/some-repo"
• "Writing Directive state: ~/directive-workspace/repos/github.com/some-org/some-repo/"

Why Not Just Vendor Directive?

Vendoring remains useful for repos that want Directive as part of their own workflow. This proposal is for a different case:

• The target repo is not mine.
• The target repo is public/open source.
• I want private planning before proposing upstream work.
• I want durable vBRIEF history across many repos.
• I do not want Directive artifacts in the target repo's git history.
• I want package-manager usage, such as npx, to work without a repo-local install.

State Location Options

The preferred default is a separate user-owned Directive workspace repo.

Pros:

• Durable and portable across machines.
• Can be private even when target repos are public.
• Git-backed history for vBRIEFs and decisions.
• Supports many target repos under one workspace.
• Avoids upstream repo pollution.

Local app data may be useful for cache or throwaway exploration, but should not be the canonical source of truth for serious vBRIEF lifecycle state.

A branch or fork of the target repo may be useful as an export/publish path, but should not be the default because it still requires write permissions or branch/fork management.

Requirements

1. Directive can initialize an external workspace outside the target repo.
2. Directive can attach a GitHub remote URL to a stable workspace path.
3. vBRIEF lifecycle files can be created and managed in the workspace without modifying the target repo.
4. Directive records target repo provenance, including owner/repo, remote URL, default branch, and observed commit SHA.
5. Commands clearly distinguish target reads from workspace writes.
6. Cache/runtime state remains gitignored or separately governed inside the workspace.
7. Existing vendored-repo behavior remains supported.
8. Exporting artifacts back into the target repo, fork, issue, or PR requires explicit user action.

Non-Goals

• Replacing the vendored install model for repos that want Directive in-tree.
• Requiring npm specifically as the only delivery mechanism.
• Writing to target repos by default.
• Solving full multi-repo program orchestration in the first slice.

Acceptance Criteria

• A user can create a Directive workspace in a separate directory or repo.
• A user can attach at least one GitHub repo URL to that workspace.
• Directive creates the expected project definition and vBRIEF lifecycle directories under the workspace namespace.
• Running a planning/triage flow for the target repo writes no files into the target checkout.
• Diagnostics and doctor output show both the target repo and workspace location.
• The workspace layout supports multiple target repos without path collisions.
• Documentation explains when to use vendored mode vs external workspace mode.

Related Issues

• Proposal: Publish Deft as an NPM + PIP CLI (agent-first distribution) #11: package-manager distribution via npm/PIP CLI
• RFC: Migrate Deft Directive's implementation from Python to TypeScript on the RivetOS agent runtime #1530: TypeScript/RivetOS migration RFC
• RFC: vendored-done-right as the canonical on-disk install model (target v0.39.2) #1428 / vendored install model: existing in-repo install approach
• SCM-agnostic auto-commit/PR of the vendored .deft/core deposit (Go installer, via scm.call adapter) #1439 / Optional git-submodule tracking mode for .deft/core (carved from #1050) #1446: alternate approaches to managing .deft/core delivery and tracking

[MScottAdams]

Deep-think: External Directive workspace mode

Author deep-think on this RFC. Code references are pinned to commit eb7f7a7 so line anchors stay accurate as files move. This is analysis only — no umbrella or child issues are filed yet (deliberately deferred until the work is committed to).

TL;DR

• The RFC is sound and the layered design is right.
• The framing slightly under-sells the codebase: the data plane (read one repo → write vBRIEF/cache somewhere else) is already ~60–70% decoupled and partly works today via existing flags.
• The real cost is in the control plane: framework-location resolution, the Taskfile-bound command surface, the single-project session ritual/gates, and structured provenance.
• External mode is effectively a sibling of Proposal: Publish Deft as an NPM + PIP CLI (agent-first distribution) #11 (package distribution) / RFC: Migrate Deft Directive's implementation from Python to TypeScript on the RivetOS agent runtime #1530 (TS migration), not independent of it.
• Smallest honest first slice: a read-only external triage/ingest flow for one target, because the ingest verb + SCM shim + cache already accept the needed knobs.

What's actually being asked

Decouple two things the current "project root" conflates:

• Read surface — a GitHub repo (issues, source, metadata) that may be unvendored and not yours.
• Write surface — where vBRIEF lifecycle state, PROJECT-DEFINITION, and cache live.

Drive triage/planning/lifecycle for some-org/some-repo while writing zero Directive artifacts into that checkout, persisting state under a user-owned workspace namespaced per target (<ws>/repos/github.com/<owner>/<repo>/).

Reality check: the data plane is already mostly decoupled

The RFC says Directive "assumes the project being worked on can host Directive artifacts." That's true of the install model and session ritual, but the data-plane seams already exist:

1. Root vs. repo are already distinct concepts. _project_context resolves project_root (where state lives) and project_repo (the GitHub slug) through independent precedence chains — resolve_project_root (--project-root / $DEFT_PROJECT_ROOT) and resolve_project_repo (--repo / $DEFT_PROJECT_REPO). They are not required to point at the same place.
2. The ingest verb is already external-capable. issue_ingest takes three independent inputs — --repo and --project-root plus --vbrief-dir, wired together in main. So task issue:ingest --repo some-org/some-repo --vbrief-dir <ws>/.../vbrief already reads one repo and writes elsewhere.
3. GitHub reads don't require CWD == target. scm.call(..., cwd=...) forwards --repo OWNER/NAME to gh/ghx, and the REST path requires explicit --repo. Target reads are repo-addressed, not CWD-addressed.
4. The cache is already per-repo namespaced. entry_dir keys entries as <cache_root>/github-issue/<owner>/<repo>/<N> with an injectable cache_root; the <owner>/<repo>/<N> key shape is already enforced. The RFC's repos/github.com/owner/repo/.deft-cache layout is a superset of what exists.
5. PROJECT-DEFINITION write is root-relative. project_definition_path(project_root) is just project_root/vbrief/PROJECT-DEFINITION.vbrief.json. Point project_root at a workspace path and it works unchanged.

Where co-location is genuinely baked in (the control plane)

The five hard couplings (expand)

1. Framework-location assumption in the gate stack. _resolve_preflight_path probes only <project-root>/.deft/core/scripts/, <project-root>/deft/scripts/, <project-root>/scripts/. doctor resolves AGENTS.md, QUICK-START.md, and the VERSION manifest strictly under project_root. In external / npx mode the framework comes from the package, not the target or even the workspace. This is the deepest assumption and it collides head-on with the Implementation-intent inference is non-deterministic: agents spawn coding sub-agents from lifecycle/PR-process language without explicit action-verb authorization #810 Implementation Intent Gate and the session-start ritual (task doctor, task vbrief:preflight).
2. The command surface is Taskfile-bound. Every verb is task X resolved through a root Taskfile that includes: ./.deft/core/Taskfile.yml. The RFC's deft workspace … / npx @deftai/directive … implies a standalone CLI that does not need a co-located Taskfile — i.e. the Proposal: Publish Deft as an NPM + PIP CLI (agent-first distribution) #11 / RFC: Migrate Deft Directive's implementation from Python to TypeScript on the RivetOS agent runtime #1530 direction.
3. Session ritual / AGENTS.md are single-project. The five-step ritual assumes exactly one active project root, one PROJECT-DEFINITION, one policy, one WIP cap. A workspace fanning out to N targets makes "which AGENTS.md / which policy / which cap" ambiguous.
4. No structured provenance. RFC requirement make /deft read-only #4 (owner/repo, remote URL, default branch, observed SHA) has no typed home today — only freeform narratives.Origin and x-vbrief/github-issue references.
5. Gates rooted at one project root. verify:branch, verify:wip-cap, the triage cache, and verify:cache-fresh all assume single-root. Branch policy especially: in external mode you commit to the workspace repo, never the target, so the branch gate's semantics need re-scoping, not just re-pathing.

Sharpest risks / failure modes

• issue:ingest and reconcile:issues query deftai/directive instead of consumer project's GitHub repo (same root cause as #535) #538-class mis-detection, reintroduced. resolve_project_repo step 3 falls back to git remote get-url origin of the project root. In a workspace that is itself a git repo, this silently detects the user's private workspace origin as the "target." External mode MUST force explicit --target / $DEFT_PROJECT_REPO and forbid the git-remote fallback.
• Gate fail-open, reintroduced. If preflight/doctor can't find the framework under an external project_root, Implementation-intent inference is non-deterministic: agents spawn coding sub-agents from lifecycle/PR-process language without explicit action-verb authorization #810 becomes unreachable or fails open — the exact bug class Install/refresh contract has no self-healing path: agent gets stuck in a no-op Case G loop when install layout disagrees with AGENTS.md #1046 / Implementation Intent Gate (#810): Taskfile target hardcodes deft/scripts/preflight_implementation.py; safety gate fails open in v0.27 install layout #1047 closed. External mode must teach the resolver a package/global framework location before any implementation flow is allowed externally.
• Target pollution via default cache root. DEFAULT_CACHE_ROOT = Path(".deft-cache") is CWD-relative. If CWD is the target checkout, cache writes land in the target — violating requirements Deft asks programming languages too early in the cycle, and limited options #6 / don't commit until questionnaires are finished #8. External mode must force cache_root into the workspace.

Design decisions to settle

• Per-target project root vs. workspace index. Recommend: each target = a full project root (<ws>/repos/github.com/<owner>/<repo>/ with its own vbrief/ + cache), reusing ~100% of existing path logic, plus a thin workspace-level manifest for attach bookkeeping. Avoid inventing a new multi-root state shape.
• Resolution collapse. Define --workspace + --target → derive project_root = <ws>/repos/github.com/<owner>/<repo> and project_repo = <owner>/<repo>; mirror as $DEFT_WORKSPACE / $DEFT_TARGET. A thin adapter over the existing two-knob resolver, not a rewrite.
• One mode resolver, not two code paths. Requirement double prompting for programming languages during bootstrap+ #7 (vendored keeps working) is best served by a single "where is the framework / where is state" resolver with a detected mode, so vendored and external share the gate stack.
• Sequencing. Provenance + the workspace→root/repo adapter can land now against the Python/Task surface; the npx-facing deft workspace verbs and the framework-location decoupling should ride with Proposal: Publish Deft as an NPM + PIP CLI (agent-first distribution) #11 / RFC: Migrate Deft Directive's implementation from Python to TypeScript on the RivetOS agent runtime #1530.

Recommended first slice (tracer bullet)

A read-only external triage/ingest flow for a single target, because ingest + scm.call + cache already accept the needed knobs:

• deft workspace init + deft workspace attach <url> → create <ws>/repos/github.com/<owner>/<repo>/ with vbrief/ lifecycle dirs + a PROJECT-DEFINITION carrying a typed provenance block (owner/repo, remoteUrl, defaultBranch, observedSha).
• Run issue:ingest / triage against it with cache_root forced into the workspace; assert zero writes to the target checkout.
• Diagnostics print both sides ("Reading target: …" / "Writing state: …").
• Defer doctor/preflight/build/branch-gate (everything needing the framework co-located) until the package-CLI decision lands.

Proposed decomposition (not yet filed)

flowchart LR
  S1["Slice 1 — Provenance<br/>typed provenance block on PROJECT-DEFINITION"]
  S2["Slice 2 — Resolution adapter<br/>workspace+target -> root/repo; kill git-remote fallback"]
  S3["Slice 3 — Read-only tracer<br/>workspace init/attach + external ingest/triage"]
  S4["Slice 4 — Framework-location decoupling<br/>doctor/preflight off project_root (co-design #11/#1530)"]
  S5["Slice 5 — Gate re-scoping<br/>branch/WIP/cache-fresh for workspace vs target"]

  S1 --> S3
  S2 --> S3
  S4 --> S5
  S3 -.enables.-> S4

Loading

• Slices 1 & 2 are foundational and parallelizable; they land against the existing Python/Task surface.
• Slice 3 depends on 1 + 2 and proves the read/write boundary end-to-end.
• Slice 4 is gated on the Proposal: Publish Deft as an NPM + PIP CLI (agent-first distribution) #11 / RFC: Migrate Deft Directive's implementation from Python to TypeScript on the RivetOS agent runtime #1530 package-CLI direction and unblocks external implementation flows.
• Slice 5 depends on 4.

Relationship to related issues

• Proposal: Publish Deft as an NPM + PIP CLI (agent-first distribution) #11 (package distribution) and RFC: Migrate Deft Directive's implementation from Python to TypeScript on the RivetOS agent runtime #1530 (TS migration) — external mode's deft workspace / npx surface is really part of this. Hard to ship cleanly while the surface is Taskfile-bound.
• RFC: vendored-done-right as the canonical on-disk install model (target v0.39.2) #1428 (vendored install model) — stays the default; requirement double prompting for programming languages during bootstrap+ #7 keeps it working via a single mode resolver.
• SCM-agnostic auto-commit/PR of the vendored .deft/core deposit (Go installer, via scm.call adapter) #1439 / Optional git-submodule tracking mode for .deft/core (carved from #1050) #1446 (.deft/core delivery) — the framework-location decoupling in Slice 4 should reuse whatever delivery decision these land on.

Bottom line

The valuable correction to the framing: the data plane is already mostly decoupled; the real work is the control plane (framework-location resolution, the Taskfile→CLI surface, single-project ritual/gates, and provenance). Recommend eventually splitting into the five slices above — but only when the work is committed to. For now this comment is the durable record.