@deftai/directive-content 0.55.0

package/scm/github.md

@@ -0,0 +1,265 @@
+# GitHub Standards
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**See also**: [main.md](../../main.md) | [git.md](./git.md) | [changelog.md](./changelog.md)
+
+**Stack**: gh CLI 2.0+, GitHub Actions, Conventional Commits, issue/PR workflows
+
+## Standing gh CLI Rules
+
+Rules that apply to every `gh` invocation, regardless of context.
+
+- ! Use `--body-file` for PR and issue bodies longer than one line -- inline `--body` strings break on special characters, newlines, and shell escaping across platforms
+- ! For Markdown-rich issue bodies, PR bodies, and issue/PR comments, prefer the canonical safe wrapper: `task scm:body:* -- --repo OWNER/NAME ... --body-file <path>`. It reads UTF-8 body text from a file or stdin, sends JSON to `gh api` without shell interpolation, and immediately performs live `gh` read-back.
+- ! Never place Markdown containing backticks inside a double-quoted shell command. In Bash and zsh, a body fragment like ``"include `ghx`"`` runs command substitution before `gh` receives the text, corrupting the posted body.
+- ! Write `--body-file` temp files to the OS temp directory, not the worktree -- writing temp files inside the worktree triggers `rm` denylist collisions that block autonomous swarm agents in Warp (the agent cannot delete files via `rm` in autonomous mode)
+  - **PowerShell:**
+    ```powershell
+    $bodyFile = [System.IO.Path]::GetTempFileName()
+    [System.IO.File]::WriteAllText($bodyFile, $content, [System.Text.UTF8Encoding]::new($false))
+    gh pr create --title "feat: example" --body-file $bodyFile
+    ```
+  - **Unix (bash/zsh):**
+    ```bash
+    bodyFile=$(mktemp)
+    echo "$content" > "$bodyFile"
+    gh pr create --title "feat: example" --body-file "$bodyFile"
+    ```
+  - No explicit `rm` is needed after `gh pr create` -- the file lives outside the worktree, which is the key advantage: it eliminates the `rm` step that collides with the Warp autonomous agent `rm` denylist. (OS temp directories are eventually cleaned by the OS on Unix/macOS; on Windows they persist until manually purged, but agent cleanup is not required.)
+- ! Immediately verify after every create or edit operation:
+  - After `gh pr create`: run `gh pr view <number>` to confirm title, body, and labels rendered correctly
+  - After `gh issue create`: run `gh issue view <number>` to confirm body content
+  - After `gh pr edit`: re-fetch and verify the edited field
+- ! Use live `gh` for immediate read-back after a mutation. Do not use `ghx` for the first verification GET because it may serve a cached stale response.
+- ~ Prefer `gh api` for structured/programmatic queries (filtering, bulk reads, JSON output) and `gh pr`/`gh issue` for quick ad-hoc commands
+- ⊗ Construct multi-line `--body` strings inline in shell commands -- always write to a temp file and use `--body-file`
+- ⊗ Construct Markdown-rich `gh api -f body="..."` or `gh issue comment --body "..."` commands when the body contains backticks, dollar signs, quotes, or fenced code blocks -- use a body file and the `scm:body:*` wrapper instead
+- ⊗ Write `--body-file` temp files inside the worktree or repository directory -- always use the OS temp directory (`$env:TEMP` on PowerShell, `$TMPDIR` or `/tmp` on Unix)
+
+## Safe Markdown Body Posting (#1555)
+
+Use `scripts/github_body.py` through the task surface whenever an agent needs to post or edit Markdown-rich GitHub text. The helper accepts `--body-file <path>` or `--body-file -`, wraps the body as JSON inside Python, calls `gh api --input -` through the UTF-8-safe subprocess helper, and prints the live read-back object returned by `gh`.
+
+Safe issue creation:
+
+```bash
+task scm:body:issue:create -- \
+  --repo deftai/directive \
+  --title "tooling: safe body example" \
+  --body-file "$bodyFile"
+```
+
+Safe issue or PR comment creation:
+
+```bash
+task scm:body:comment:create -- \
+  --repo deftai/directive \
+  --issue 1555 \
+  --body-file "$bodyFile"
+```
+
+Safe issue comment edit with live read-back:
+
+```bash
+task scm:body:comment:edit -- \
+  --repo deftai/directive \
+  --comment 123456789 \
+  --body-file "$bodyFile"
+```
+
+The helper's stdout is the live post-mutation GitHub object, so inspect the `body` field from that output first. If you need a second manual verification, use live REST through `gh api repos/OWNER/REPO/issues/comments/<id>` or `gh api repos/OWNER/REPO/issues/<number>`; do not use `ghx` for immediate read-back after the mutation because it may return a cached GET.
+
+## PR Workflow Conventions
+
+### Merge Strategy
+
+- ! Use squash-merge as the default merge method: `gh pr merge --squash --delete-branch`
+- ~ Squash-merge keeps the mainline history linear and readable -- one commit per PR
+- ? Use merge commits only when preserving individual commit history is explicitly required (e.g., vendor imports)
+- ⊗ Use rebase-merge on PRs with multiple commits unless the author explicitly requests it
+
+### Branch Lifecycle
+
+- ! Create feature branches from `master` (or the project's default branch)
+- ! Each branch serves a single purpose -- one issue or one cohesive change
+- ! Include closing keywords in the PR body (`Closes #N`, `Fixes #N`) so GitHub auto-closes issues on merge
+- ! Delete the branch after merge (`--delete-branch` flag on `gh pr merge`)
+- ⊗ Reuse a branch for a second PR after the first has merged
+- ~ Name branches descriptively: `docs/add-github-guide`, `fix/bootstrap-loop`, `feat/swarm-phase0`
+
+### PR Standards
+
+- ! Use Conventional Commits format for PR titles
+- ~ Keep PRs small (< 400 lines changed ideal)
+- ! Ensure all CI checks pass before requesting review
+- ~ Link to related issues using closing keywords
+- ~ Explain "why" not just "what" in the PR description
+- ! Run `task check` before opening a PR
+
+### Review Guidelines
+
+**Approval criteria (MUST be met)**:
+
+- Code follows language standards (python.md, go.md, cpp.md)
+- Tests pass with required coverage threshold
+- Conventional Commits format
+- No security vulnerabilities
+- Documentation updated
+- No breaking changes (or properly documented)
+
+**Review tone (SHOULD follow)**:
+
+- Be constructive and specific
+- Explain "why" not just "what"
+- Suggest alternatives when requesting changes
+- Focus on correctness, maintainability, performance (in that order)
+
+## Post-Merge Issue Verification
+
+! After a PR is squash-merged, verify that all referenced issues were actually closed. Squash merges can silently fail to process closing keywords (`Closes #N`, `Fixes #N`) from the PR body (#167).
+
+1. ! For each issue referenced with a closing keyword in the PR body, run:
+   ```
+   gh issue view <N> --json state --jq .state
+   ```
+2. ! If the issue state is not `CLOSED`, close it manually with a comment referencing the merged PR:
+   ```
+   gh issue close <N> --comment "Closed by #<PR> (squash merge -- auto-close did not trigger)"
+   ```
+3. ~ This applies to ALL PR merges, not just swarm runs. See also: `skills/deft-review-cycle/SKILL.md` Post-Merge Verification, `skills/deft-directive-swarm/SKILL.md` Phase 6 Step 2.
+
+## Windows / PowerShell Encoding Guidance
+
+PowerShell 5.x (Windows default) uses UTF-16LE internally and may inject a BOM or transcode `gh` CLI output unexpectedly. These issues are silent -- files look correct in the editor but fail on `edit_files` or `git diff`.
+
+- ! Use UTF-8 without BOM for all `--body-file` content written from scripts or agents
+- ! On PowerShell 5.x, set encoding before writing temp files:
+  ```powershell
+  [System.IO.File]::WriteAllText($path, $content, [System.Text.UTF8Encoding]::new($false))
+  ```
+- ~ Avoid piping `gh` output through PowerShell 5.x redirection (`>`, `Out-File`) -- these default to UTF-16LE; use .NET `WriteAllText` with the BOM-free constructor instead (see rule below)
+- ~ Prefer PowerShell 7+ (`pwsh`) which defaults to UTF-8 without BOM
+- ! Use `Get-Content -Raw` to read a file as a single string -- reading without `-Raw` processes line-by-line and can inject BOM characters or silently mangle Unicode characters (em-dashes, curly quotes) when the file is re-written
+- ! For BOM-safe file writes after agent reads, use `[System.IO.File]::WriteAllText($path, $content, [System.Text.UTF8Encoding]::new($false))` -- never use `Set-Content` (even with `-Encoding UTF8`) or `Out-File` in PS 5.1, as both inject a BOM regardless of the `-Encoding` flag (`Out-File -Encoding utf8NoBOM` requires PS 7+ and is unavailable in PS 5.1)
+
+**Rationale**: PS 5.1 defaults to UTF-16LE for `Set-Content` and UTF-8-with-BOM for some paths, causing silent mojibake on round-trip. The combination of `Get-Content -Raw` for reads and `[System.IO.File]::WriteAllText` for writes is the only reliable BOM-safe round-trip pattern.
+
+### Warp Terminal Multi-Line String Handling
+
+- ! Never paste multi-line PowerShell string literals (here-strings `@" ... "@`) directly into the Warp agent input box -- Warp splits multi-line input across separate command blocks, causing syntax errors or silent truncation. Always write multi-line PS content to a temp file first (e.g. `[System.IO.File]::WriteAllText($tmpFile, $content, [System.Text.UTF8Encoding]::new($false))`), then use the temp file path in subsequent commands
+
+## Windows / ASCII Conventions for Machine-Editable Sections
+
+Agent `edit_files` operations can fail when structured file sections contain Unicode characters that do not round-trip cleanly through Windows toolchains (xref warpdotdev/warp#9022). The following rules apply to **machine-editable structured sections**: ROADMAP.md phase bodies, CHANGELOG.md entries, and Open Issues Index rows.
+
+- ~ In machine-editable structured sections, prefer ASCII punctuation:
+  - Use `--` instead of em-dash
+  - Use `->` instead of arrow characters
+  - Avoid emoji in body text (emoji in headings or decorative positions are acceptable)
+- ! Never use Unicode em-dashes, curly quotes, or non-ASCII arrow characters in CHANGELOG.md entries or ROADMAP.md index rows -- these cause `edit_files` search/replace mismatches when the tool's internal encoding differs from the file's byte representation
+- ~ Use straight quotes (`"`, `'`) rather than curly/smart quotes in all machine-edited files
+- ? Prose-only sections (README narrative, philosophy docs) may use Unicode freely since they are rarely machine-edited
+
+**Rationale**: The `edit_files` tool performs exact byte-string matching. When Windows agents write files through encoding layers that silently substitute characters (e.g., em-dash `\u2014` vs. `--`), subsequent search/replace operations fail because the stored bytes no longer match the search string. Sticking to ASCII in structured sections eliminates this class of failure.
+
+## Issue Workflow
+
+**Best practices**:
+- ~ Search for duplicates before creating
+- ! Include reproduction steps, expected/actual behavior, environment details
+- ~ Apply appropriate labels and assign when taking ownership
+- ~ Link related issues and PRs
+
+### Issue Labels
+
+**Priority**: `priority:critical` (production down), `priority:high` (major broken), `priority:medium` (important, not blocking), `priority:low` (nice to have)
+
+**Type**: `bug`, `feat`, `docs`, `refactor`, `test`, `chore`
+
+**Status**: `status:blocked`, `status:in-progress`, `status:needs-info`, `status:wontfix`
+
+### Post-1.0.0 Issue Linking
+
+Following a v1.0.0 release, commits:
+
+- ! link to existing or new issues for: Features, bugs, breaking changes, architecture decisions
+- ≉ create issues for: Typos, formatting, dependency bumps, refactoring same code
+- ~ create issues for: Anything someone might search for later, or that needs discussion
+
+**Format**: Reference issues in commit messages using `Closes #123`, `Fixes #456`, or `Relates to #789`
+
+## GitHub Actions Best Practices
+
+**CI Workflows**:
+- ~ Provide fast feedback (fail fast, cache dependencies)
+- ~ Use matrix testing for multiple versions
+- ! Run `task check` for quality gates
+- ~ Upload coverage reports
+
+**Security**:
+- ! Use GitHub Secrets for CI/CD credentials
+- ⊗ Commit secrets to repo
+- ~ Keep secrets in `secrets/` dir locally (gitignored)
+- ~ Rotate secrets regularly
+
+## Branch Protection
+
+**Recommended settings** for `main`:
+- ! Require PR reviews (1+ approvals)
+- ! Require status checks to pass
+- ! Require branches to be up to date
+- ~ Require conversation resolution
+- ~ Require linear history
+- ⊗ Allow force pushes
+- ⊗ Allow deletions
+
+## Destructive gh verbs (#1019)
+
+A detection-bound gate (`scripts/preflight_gh.py`) refuses three classes of destructive surface before they execute, complementing the #747 branch-protection gate which already refuses commits to the default branch:
+
+- `delete_repo` -- `gh repo delete <owner/repo>` and `gh api -X DELETE repos/<owner>/<repo>[/...]`. Irreversible.
+- `force_push_default` -- `git push --force` / `--force-with-lease` / `+refspec` targeting `master` or `main`.
+- `admin_merge` -- `gh pr merge --admin` (bypasses branch-protection required reviews).
+
+Three enforcement surfaces back the gate:
+
+1. `.githooks/pre-push` invokes `preflight_gh.py --pre-push-stdin` after the #747 branch gate, refusing any push that touches the default branch (force-push or otherwise). Install via `task setup` (idempotent `git config core.hooksPath .githooks`); verify via `task verify:hooks-installed`.
+2. `task verify:destructive-gh-verbs` is wired into the `task check` aggregate. It runs `preflight_gh.py --self-test`, which drives a built-in fixture table through the classifier so a future edit that introduces a false negative / false positive fails CI immediately.
+3. Agent pre-execution callers can invoke `python scripts/preflight_gh.py --command "<full command>"` to classify a candidate verb before it executes. Three-state exit (0 allowed / 1 destructive refused / 2 config error) mirrors `scripts/preflight_branch.py`.
+
+**Override paths:**
+
+- `DEFT_ALLOW_DESTRUCTIVE_GH_VERBS=1` -- per-shell emergency env-var bypass. Mirrors `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT` (#747). The gate prints an explicit `policy bypassed for this session` line so the bypass is auditable after the fact.
+- For repo deletion specifically: prefer the GitHub web UI's archive-or-delete prompt -- archiving is reversible, the gate is not opining on it.
+- For an admin merge: the canonical recovery is to request review through the normal flow. The `--admin` flag is gated because the most-common legitimate use case (release hot-fix) is rare enough that documenting an explicit bypass is cheaper than letting the verb pass by default.
+
+**Out of scope (v1):** a PATH-shim that intercepts `gh` at the command layer is deferred -- the consent-gated install path mirrors `setup_ghx.py` (#884) and lands additively when a follow-up issue is opened. The current gate is detection-bound (pre-push hook + agent-side `--command` classifier + self-test contract) rather than execution-bound, which is sufficient to refuse the recurring failure mode that motivated #1019 (an agent with an unrestricted `gh` token executing a destructive verb).
+
+## Release Workflow (UCCPR)
+
+**UCCPR** = Update Changelog, Commit, Push, Release
+
+Standard workflow for releasing new versions:
+
+1. Update `CHANGELOG.md` -- move `[Unreleased]` entries to new version section with date
+2. Update `VERSION` constant in main script/package file
+3. Commit: `git commit -m "chore: release v<X.Y.Z>"`
+4. Push to default branch
+5. Tag: `git tag v<X.Y.Z> && git push origin v<X.Y.Z>`
+6. Release: `gh release create v<X.Y.Z> --title "Deft v<X.Y.Z>" --notes-file release-notes.md`
+
+## Compliance
+
+- ! Use Conventional Commits for all PR titles
+- ! Maintain CHANGELOG.md following [Keep a Changelog](./changelog.md) format
+- ! Use [Semantic Versioning](../meta/versioning.md) for releases
+- ! Include CHANGELOG.md content in release notes
+- ! Maintain test coverage at or above PROJECT.md threshold
+- ! Pass all CI checks before merge
+- ~ Request reviews from appropriate team members
+- ~ Link PRs to related issues
+- ~ Use gh CLI for automation where possible
+- ⊗ Force-push to protected branches
+- ! Keep PR scope focused and size reasonable
+- ! Update documentation with code changes

package/skills/deft-build/SKILL.md

@@ -0,0 +1,20 @@
+<!-- DEFT-PREAMBLE-V1 -->
+<!-- deft:deprecated-skill-redirect -->
+! Before any other instruction in this file or in the consumer AGENTS.md, run `python3 deft/run gate`.
+! If exit code is 0, continue.
+! Otherwise: read `deft/UPGRADING.md`, find the section whose "Applies when" clause matches the state vector printed by the gate, and follow that section verbatim. Respect any "Restart required" directive -- if present, stop and tell the user to start a fresh session after cleanup commands complete.
+
+# Deprecated skill path — v0.19 → v0.20 bridge
+
+This skill path is deprecated. Read `deft/QUICK-START.md` for current routing.
+The current replacement skill is `deft-directive-build` (at `skills/deft-directive-build/SKILL.md`).
+
+Do not add real content here. This file exists so that stale v0.19 `AGENTS.md` files
+that reference old `deft/skills/deft-*` paths keep working through one release cycle.
+QUICK-START.md refreshes the Deft-managed section of `AGENTS.md` to the current
+v0.20 `deft-directive-*` skill paths.
+
+See:
+- [../../QUICK-START.md](../../QUICK-START.md) — agent bootstrap + upgrade detection
+- [../../UPGRADING.md](../../UPGRADING.md) — version-by-version upgrade guide
+- [../../docs/BROWNFIELD.md](../../docs/BROWNFIELD.md) — brownfield adoption / migration

package/skills/deft-directive-article-review/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: deft-directive-article-review
+description: >-
+  Evaluate an article, paper, or post for lessons that could improve
+  directive. Analyzes two axes: how concepts improve directive's own
+  implementation, and how they improve the projects directive creates.
+  Produces filtered suggestions, iterates with the user, and optionally
+  creates GitHub issues on the directive repo. Use when evaluating an article,
+  paper, post, or URL for directive improvements, or when the user says
+  "analyze this article", "evaluate this article", or "what can we learn from
+  this for directive".
+triggers:
+  - evaluate article
+  - analyze article
+  - review article for directive
+  - extract lessons
+  - what can we learn from this
+  - article for directive
+metadata:
+  clawdbot:
+    requires:
+      bins: ["gh"]
+---
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered skill -->
+<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
+
+# Deft Article Review
+
+Evaluate an article, paper, or blog post for lessons that could improve directive —
+both how directive itself is implemented and what directive helps create.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+---
+
+## Directive Reference
+
+Use this summary to evaluate whether article ideas are genuinely novel or already covered by the framework.
+
+**Directive** is a development framework that combines indexed documentation, task automation, and AI-assisted workflows.
+
+**main.md (front door)** — Central entry/index for a Karpathy-wiki-style set of lazy-loaded markdown rules organized into sections: `coding/`, `languages/`, `interfaces/`, `tools/`, `scm/`, `contracts/`, `swarm/`, `strategies/`, `vbrief/`, and `templates/`. Agents load only what's relevant.
+
+**Taskfiles (go-task)** — Single entrypoint for all repeatable operations. Core flows: `task dev`, `task test`, `task build`, `task release`. Composed via `deps`; logic lives in scripts/binaries. Caching via `sources/generates + method: checksum`. Namespaced tasks (`docker:build`, `db:migrate`). Every user-facing task has a `desc`; internal wiring marked `internal: true`.
+
+**vbrief** — Structured JSON artifacts in `./vbrief/` covering current state and forward planning: `plan.vbrief.json` (todos/progress), `specification.vbrief.json` (project specs), `playbook-{name}.vbrief.json` (reusable playbooks), `continue.vbrief.json` (interruption recovery). Drives the full lifecycle: planning → specification → execution → checkpointing → resumption. Refreshed via `deft-sync` at session start.
+
+**Skills** — Versioned, reusable workflows triggered by keywords: `deft-setup` (bootstrap), `deft-build` (implement from spec), `deft-sync` (refresh framework + vbrief), `deft-pre-pr` (quality loop), `deft-review-cycle` (PR bot feedback), `deft-swarm` (parallel agent orchestration), `deft-roadmap-refresh` (issue triage), `deft-interview` (structured Q&A). Skills chain together and encode lessons from prior runs.
+
+## When to Use
+
+- User shares a URL, local file path, or pasted text to analyze for directive improvements
+- User says "what can we learn from this for directive" or "evaluate this article"
+- After reading a research paper, practitioner post, or technical write-up that seems relevant
+
+## Prerequisites
+
+- ! If a URL is provided, fetch and read the full content before beginning analysis
+- ! If a local file path is provided, read the file
+- ! If pasted text, work from the provided content
+- ⊗ Begin analysis before reading the full content
+
+---
+
+## Process
+
+### Step 1: Ingest the article
+
+- ! Read the full content — do not skim or skip sections
+- ~ Note the source type (research paper, practitioner blog, product docs, etc.) as it affects how much weight to give conclusions
+
+### Step 2: Evaluate Axis 1 — How can this improve directive's own implementation?
+
+Look for lessons applicable to how directive itself is built, structured, and maintained:
+
+- ! Skills and strategies: are there new skills, strategies, or workflow patterns directive should adopt?
+- ! Framework architecture: does this suggest changes to lazy loading, vBRIEF, AGENTS.md structure, or the patterns/ directory?
+- ! Agent safety and reliability: does this reveal new failure modes or defenses directive should encode?
+- ! Tooling: does this suggest new tasks, task patterns, or SCM conventions directive should add?
+- ~ Naming, directory structure, or documentation conventions worth adopting
+
+### Step 3: Evaluate Axis 2 — How can this improve the projects directive creates?
+
+Look for lessons applicable to projects that directive-guided agents build:
+
+- ! Coding standards: new rules for languages/, coding/, or patterns/ that would improve project quality
+- ! Security: new vulnerabilities or defenses projects should implement (e.g., agent trap defenses, LLM application security)
+- ! Architecture patterns: new patterns/ content for multi-agent, LLM apps, safety-critical, or other system types
+- ! Testing, observability, or deployment practices worth encoding as directive standards
+- ~ Stack recommendations or technology choices with clear rationale
+
+### Step 4: Filter and prioritize
+
+- ! Discard ideas that are not genuinely actionable or relevant — not everything in an article applies to directive
+- ! Rate each suggestion: **High** (actionable now, clear value), **Medium** (worth considering, needs evaluation), **Low/Speculative** (interesting but hypothetical)
+- ! Note which existing directive files or issues each suggestion would affect
+- ⊗ Present every idea uncritically — only surface ideas with real directive relevance
+
+### Step 5: Cross-reference open issues
+
+- ! Run `gh issue list --repo deftai/directive --state open --limit 100` to retrieve the current open issue backlog
+- ! For each suggestion from Step 4, check whether an open issue already covers it — fully or partially
+- ! If a suggestion duplicates an open issue: drop it from the proposal and note the existing issue number
+- ! If a suggestion extends or relates to an open issue: flag it as "extends #N" rather than proposing a standalone new issue
+- ~ Scan the open issue list for trends (e.g. a cluster of agent-safety issues, a cluster of pattern/ gaps) — use trends to sharpen framing or prioritization of remaining suggestions
+- ⊗ Propose a new issue for something already tracked — deduplication is mandatory
+
+### Step 6: Present suggestions to the user
+
+Present a structured summary organized by axis. For each suggestion:
+- Brief description of the idea
+- Why it's relevant to directive specifically
+- Which file(s) or directory it would affect
+- Confidence rating (High / Medium / Low)
+
+! After presenting, explicitly ask:
+> "Does any of this resonate? Do you want to modify, combine, or drop any of these before we decide what to file?"
+
+Allow the user to comment, change framing, merge suggestions, or remove any. Iterate until the user is satisfied with the set.
+
+### Step 7: Offer issue creation
+
+! Ask the user:
+> "Should I create GitHub issues for any of these? I can create one per suggestion or group related ones."
+
+- ! If yes: create issues on `deftai/directive` using `gh issue create` with:
+  - A clear title following conventional commit style (`feat(area):`, `refactor(area):`, `research(area):`, etc.)
+  - Body that describes the suggestion, the source article, and the specific directive files affected
+  - A note if the suggestion is speculative/research-grade vs. immediately actionable
+  - A reference to any related open issues ("extends #N", "related to #N")
+  - Issue-label hygiene: inspect existing repo labels with `gh label list` or the labels API, choose suitable existing labels when practical, or explicitly note that no label was applied. This is a recommendation, not a gate -- do not block issue creation solely because no label fits, and do not invent ad hoc labels outside the repo's existing label set.
+- ! After creating issues, print the issue URLs
+- ⊗ Create issues without explicit user confirmation
+
+### Step 8: Offer further exploration
+
+! After completing the above, ask:
+> "Is there anything else from this article worth exploring — related tools, referenced papers, or follow-on questions?"
+
+If yes, follow the thread. This may include fetching related URLs, evaluating referenced work, or researching specific concepts mentioned in the article.
+
+---
+
+## Anti-Patterns
+
+- ⊗ Treating every idea in the article as directive-relevant — filter aggressively
+- ⊗ Creating issues before the user approves the suggestion set
+- ⊗ Skipping the user feedback step and going straight to issue creation
+- ⊗ Summarizing without reading the full content
+- ⊗ Presenting unrated suggestions — every suggestion needs a confidence level
+- ⊗ Filing a single giant issue for all suggestions — one issue per distinct suggestion or related group
+- ⊗ Proposing a new issue without first checking whether it duplicates an open one
+- ⊗ Evaluating directive relevance without consulting the Directive Reference section above