devflow-kit 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to DevFlow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.0] - 2026-03-20
+
+### Added
+- **Version update notification** — statusline shows magenta `⬆ X.Y.Z` badge when newer devflow-kit is available (24h cached npm check, fully async)
+
+### Fixed
+- **Skimmer agent** — enforce rskim usage via `tools: ["Bash", "Read"]` platform restriction and strict sequential workflow; prevents fallback to Grep/Glob
+- **Init multiselect** — remove redundant "(optional)" suffix from plugin hints
+- **Init multiselect** — hide `audit-claude` plugin (not production-ready; still installable via `--plugin=audit-claude`)
+- **Statusline portability** — replace macOS-only `stat -f %m` with portable `get_mtime()` helper (macOS + Linux)
+
+---
+
+## [1.6.1] - 2026-03-20
+
+### Added
+- **`--dry-run` flag** for `devflow uninstall` — preview removal plan without deleting anything
+
+### Fixed
+- **Ambient skill loading** — removed `allowed-tools` restriction from ambient-router so skills actually load via the Skill tool
+- **Ambient hook preamble** — explicit Skill tool instruction ensures models invoke skills rather than responding directly
+- **Init wizard** — hide `devflow-ambient` from plugin multiselect (auto-included via ambient prompt)
+- **Working memory** — replaced broken `--resume` with transcript-based background updater
+
+---
+
 ## [1.6.0] - 2026-03-19
 
 ### Added
@@ -902,6 +928,8 @@ devflow init
 ---
 
 [Unreleased]: https://github.com/dean0x/devflow/compare/v1.4.0...HEAD
+[1.7.0]: https://github.com/dean0x/devflow/compare/v1.6.1...v1.7.0
+[1.6.1]: https://github.com/dean0x/devflow/compare/v1.6.0...v1.6.1
 [1.6.0]: https://github.com/dean0x/devflow/compare/v1.5.0...v1.6.0
 [1.5.0]: https://github.com/dean0x/devflow/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/dean0x/devflow/compare/v1.3.3...v1.4.0

package/README.md

@@ -24,6 +24,7 @@ DevFlow adds structured commands that handle the full lifecycle: specify feature
 - **Full-lifecycle implementation** — spec, explore, plan, code, validate, refine in one command
 - **Automatic session memory** — survives restarts, `/clear`, and context compaction
 - **Parallel debugging** — competing hypotheses investigated simultaneously
+- **Version notifications** — statusline shows an update badge when a newer version is available
 - **35 quality skills** — 9 auto-activating core, 8 optional language/ecosystem, plus specialized review, agent, and orchestration skills
 
 ## Quick Start
@@ -197,7 +198,6 @@ DevFlow creates project documentation in `.docs/` and working memory in `.memory
 
 .memory/
 ├── WORKING-MEMORY.md         # Auto-maintained by Stop hook
-├── PROJECT-PATTERNS.md       # Accumulated patterns across sessions
 ├── backup.json               # Pre-compact git state snapshot
 └── knowledge/
     ├── decisions.md           # Architectural decisions (ADR-NNN, append-only)
@@ -255,7 +255,10 @@ Session context is saved and restored automatically via Working Memory hooks —
 | Option | Description |
 |--------|-------------|
 | `--scope <user\|local>` | Uninstall scope (default: user) |
+| `--plugin <names>` | Comma-separated plugin names to uninstall selectively |
 | `--keep-docs` | Preserve .docs/ directory |
+| `--dry-run` | Show what would be removed without deleting anything |
+| `--verbose` | Show detailed uninstall output |
 
 ## Building from Source
 

package/dist/commands/init.js

@@ -121,14 +121,14 @@ export const initCommand = new Command('init')
     }
     else if (process.stdin.isTTY) {
         const choices = DEVFLOW_PLUGINS
-            .filter(pl => pl.name !== 'devflow-core-skills')
+            .filter(pl => pl.name !== 'devflow-core-skills' && pl.name !== 'devflow-ambient' && pl.name !== 'devflow-audit-claude')
             .map(pl => ({
             value: pl.name,
             label: pl.name.replace('devflow-', ''),
-            hint: pl.description + (pl.optional ? ' (optional)' : ''),
+            hint: pl.description,
         }));
         const preSelected = DEVFLOW_PLUGINS
-            .filter(pl => !pl.optional && pl.name !== 'devflow-core-skills')
+            .filter(pl => !pl.optional && pl.name !== 'devflow-core-skills' && pl.name !== 'devflow-ambient')
             .map(pl => pl.name);
         const pluginSelection = await p.multiselect({
             message: 'Select plugins to install',
@@ -284,6 +284,10 @@ export const initCommand = new Command('init')
     if (pluginsToInstall.length > 0 && coreSkillsPlugin && !pluginsToInstall.includes(coreSkillsPlugin)) {
         pluginsToInstall = [coreSkillsPlugin, ...pluginsToInstall];
     }
+    const ambientPlugin = DEVFLOW_PLUGINS.find(p => p.name === 'devflow-ambient');
+    if (ambientEnabled && ambientPlugin && !pluginsToInstall.includes(ambientPlugin)) {
+        pluginsToInstall.push(ambientPlugin);
+    }
     const { skillsMap, agentsMap } = buildAssetMaps(pluginsToInstall);
     // Install: try native CLI first, fall back to file copy
     const cliAvailable = isClaudeCliAvailable();

package/dist/commands/uninstall.d.ts

@@ -9,5 +9,14 @@ export declare function computeAssetsToRemove(selectedPlugins: PluginDefinition[
     agents: string[];
     commands: string[];
 };
+/**
+ * Format a dry-run plan showing what would be removed.
+ * Pure function — no I/O, fully testable.
+ */
+export declare function formatDryRunPlan(assets: {
+    skills: string[];
+    agents: string[];
+    commands: string[];
+}, extras?: string[]): string;
 export declare const uninstallCommand: Command;
 //# sourceMappingURL=uninstall.d.ts.map

package/dist/commands/uninstall.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { promises as fs } from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getInstallationPaths, getClaudeDirectory, getDevFlowDirectory, getManagedSettingsPath } from '../utils/paths.js';
@@ -46,13 +46,37 @@ export function computeAssetsToRemove(selectedPlugins, allPlugins) {
     }
     return { skills, agents, commands };
 }
+/**
+ * Format a dry-run plan showing what would be removed.
+ * Pure function — no I/O, fully testable.
+ */
+export function formatDryRunPlan(assets, extras) {
+    const skills = [...new Set(assets.skills)];
+    const agents = [...new Set(assets.agents)];
+    const commands = [...new Set(assets.commands)];
+    const hasAssets = skills.length > 0 || agents.length > 0 || commands.length > 0;
+    const hasExtras = extras && extras.length > 0;
+    if (!hasAssets && !hasExtras) {
+        return 'Nothing to remove.';
+    }
+    const lines = [];
+    if (skills.length > 0)
+        lines.push(`Skills (${skills.length}): ${skills.join(', ')}`);
+    if (agents.length > 0)
+        lines.push(`Agents (${agents.length}): ${agents.join(', ')}`);
+    if (commands.length > 0)
+        lines.push(`Commands (${commands.length}): ${commands.join(', ')}`);
+    if (hasExtras)
+        lines.push(`Extras: ${extras.join(', ')}`);
+    return lines.join('\n');
+}
 /**
  * Uninstall plugin using Claude CLI
  */
 function uninstallPluginViaCli(scope) {
     try {
         const cliScope = scope === 'local' ? 'project' : 'user';
-        execSync(`claude plugin uninstall devflow --scope ${cliScope}`, { stdio: 'inherit' });
+        execFileSync('claude', ['plugin', 'uninstall', 'devflow', '--scope', cliScope], { stdio: 'inherit' });
         return true;
     }
     catch {
@@ -77,8 +101,10 @@ export const uninstallCommand = new Command('uninstall')
     .option('--scope <type>', 'Uninstall from specific scope only (default: auto-detect all)', /^(user|local)$/i)
     .option('--plugin <names>', 'Uninstall specific plugin(s), comma-separated (e.g., implement,review)')
     .option('--verbose', 'Show detailed uninstall output')
+    .option('--dry-run', 'Show what would be removed without actually removing anything')
     .action(async (options) => {
-    p.intro(color.bgRed(color.white(' Uninstalling DevFlow ')));
+    const dryRun = options.dryRun ?? false;
+    p.intro(color.bgRed(color.white(dryRun ? ' DevFlow Uninstall (dry run) ' : ' Uninstalling DevFlow ')));
     const verbose = options.verbose ?? false;
     // Parse plugin selection
     let selectedPluginNames = [];
@@ -121,7 +147,7 @@ export const uninstallCommand = new Command('uninstall')
             p.log.info('Checked user scope (~/.claude/) and local scope (git-root/.claude/)');
             process.exit(1);
         }
-        if (scopesToUninstall.length > 1) {
+        if (scopesToUninstall.length > 1 && !dryRun) {
             if (process.stdin.isTTY) {
                 const scopeChoice = await p.select({
                     message: 'Found DevFlow in multiple scopes. Uninstall from:',
@@ -144,6 +170,36 @@ export const uninstallCommand = new Command('uninstall')
             }
         }
     }
+    // === DRY RUN: show plan and exit ===
+    if (dryRun) {
+        p.log.info(`Scope(s): ${scopesToUninstall.join(', ')} (dry-run shows all detected scopes)`);
+        const assets = isSelectiveUninstall
+            ? computeAssetsToRemove(selectedPlugins, DEVFLOW_PLUGINS)
+            : computeAssetsToRemove(DEVFLOW_PLUGINS, DEVFLOW_PLUGINS);
+        // Detect extras that would be cleaned up (full uninstall only)
+        const extras = [];
+        if (!isSelectiveUninstall) {
+            const docsDir = path.join(process.cwd(), '.docs');
+            const memoryDir = path.join(process.cwd(), '.memory');
+            try {
+                await fs.access(docsDir);
+                extras.push('.docs/');
+            }
+            catch { /* noop */ }
+            try {
+                await fs.access(memoryDir);
+                extras.push('.memory/');
+            }
+            catch { /* noop */ }
+            extras.push('hooks in settings.json', 'scripts in ~/.devflow/');
+        }
+        const plan = formatDryRunPlan(assets, extras.length > 0 ? extras : undefined);
+        for (const line of plan.split('\n')) {
+            p.log.info(line);
+        }
+        p.outro(color.dim('No changes made (dry run)'));
+        return;
+    }
     const cliAvailable = isClaudeCliAvailable();
     // Uninstall from each scope
     for (const scope of scopesToUninstall) {

package/dist/utils/post-install.js

@@ -448,7 +448,6 @@ export async function migrateMemoryFiles(verbose, cwd) {
     const memoryDir = path.join(root, '.memory');
     const migrations = [
         { src: path.join(docsDir, 'WORKING-MEMORY.md'), dest: path.join(memoryDir, 'WORKING-MEMORY.md') },
-        { src: path.join(docsDir, 'patterns.md'), dest: path.join(memoryDir, 'PROJECT-PATTERNS.md') },
         { src: path.join(docsDir, 'working-memory-backup.json'), dest: path.join(memoryDir, 'backup.json') },
     ];
     let migrated = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Agentic Development Toolkit for Claude Code - Enhance AI-assisted development with intelligent commands and workflows",
   "type": "module",
   "bin": {

package/plugins/devflow-accessibility/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.6.0",
+  "version": "1.7.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-ambient/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.6.0",
+  "version": "1.7.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-ambient/agents/skimmer.md

@@ -1,39 +1,88 @@
 ---
 name: Skimmer
-description: Codebase orientation using skim to identify relevant files, functions, and patterns for a feature or task
+description: Codebase orientation using rskim to identify relevant files, functions, and patterns for a feature or task
+tools: ["Bash", "Read"]
 skills: knowledge-persistence
 model: inherit
 ---
 
 # Skimmer Agent
 
-You are a codebase orientation specialist using `skim` to efficiently understand codebases. Extract structure without implementation noise - find entry points, data flow, and integration points quickly.
+You are a codebase orientation specialist. You use `npx rskim` exclusively for code exploration — never Grep, Glob, or manual file searches. Your output gives implementation agents a clear map of relevant files, functions, and integration points.
 
 ## Input Context
 
 You receive from orchestrator:
 - **TASK_DESCRIPTION**: What feature/task needs to be implemented or understood
 
-## Responsibilities
+## Workflow
 
-1. **Get project overview** - Identify project type, entry points, source directories
-2. **Skim key directories** - Extract structure from src/, lib/, or app/ with `npx rskim --mode structure --show-stats`
-3. **Search for task-relevant code** - Find files matching task keywords
-4. **Identify integration points** - Exports, entry points, import patterns
-5. **Generate orientation summary** - Structured output for implementation planning
-6. **Check project knowledge** - If `.memory/knowledge/decisions.md` exists, read its `<!-- TL;DR: ... -->` first-line comment and include active decision count in orientation under "### Active Decisions". Only the TL;DR is read here (not full entries) — this is intentional for token efficiency; agents that need full entries read the file themselves.
+Execute these steps in order. Do NOT skip steps or reorder.
 
-## Tool Invocation
+### Step 1: Project Overview
 
-Always invoke skim via `npx rskim`. This works whether or not skim is globally installed — npx downloads and caches it transparently.
+Run `ls` on the project root via Bash to identify source directories and project type. Then Read the project manifest (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.) to understand the project.
 
-## Skim Modes
+**CRITICAL**: Never run `npx rskim .` or `npx rskim` on the repo root — it scans ALL files including `node_modules/` and produces millions of tokens. Always target specific source directories.
 
-| Mode | Use When | Command |
-|------|----------|---------|
-| `structure` | High-level overview | `npx rskim src/ --mode structure` |
-| `signatures` | Need API/function details | `npx rskim src/ --mode signatures` |
-| `types` | Working with type definitions | `npx rskim src/ --mode types` |
+### Step 2: Primary Source Skim
+
+Run rskim on the main source directory with a token budget:
+
+```bash
+npx rskim src/ --tokens 15000 --show-stats
+```
+
+The `--tokens` flag auto-cascades through modes (full → minimal → structure → signatures → types) to fit within the budget. Let it choose the mode — do not specify `--mode` when using `--tokens`.
+
+If `--tokens` flag errors (older rskim version), fall back to:
+```bash
+npx rskim src/ --mode structure --show-stats
+```
+
+### Step 3: Secondary Directories (if relevant to task)
+
+Skim additional directories with smaller budgets:
+
+```bash
+npx rskim tests/ --tokens 5000 --show-stats
+npx rskim scripts/ --tokens 5000 --show-stats
+```
+
+Only skim directories relevant to the task description.
+
+### Step 4: Deep Inspection
+
+For specific files needing detailed view, use rskim with full mode:
+
+```bash
+npx rskim path/to/file.ts --mode full
+```
+
+Use this instead of Read for code files.
+
+### Step 5: Project Knowledge
+
+If `.memory/knowledge/decisions.md` exists, Read its `<!-- TL;DR: ... -->` first-line comment and include active decision count in orientation under "### Active Decisions". Only the TL;DR is read here — this is intentional for token efficiency.
+
+### Step 6: Generate Summary
+
+Produce the orientation summary in the output format below.
+
+## rskim Reference
+
+| Flag | Effect |
+|------|--------|
+| `--tokens N` | Token budget — auto-selects best mode to fit within N tokens |
+| `--mode minimal` | Maximum compression (~85-90% reduction) |
+| `--mode structure` | Architecture overview (~60-70% reduction) |
+| `--mode signatures` | API/function details (~85-92% reduction) |
+| `--mode types` | Type definitions only (~90-95% reduction) |
+| `--mode full` | Complete file content (0% reduction) |
+| `--show-stats` | Show original vs skimmed token counts |
+| `--max-lines N` | AST-aware truncation (keeps types/signatures over imports/bodies) |
+
+**Preferred**: Use `--tokens N` instead of choosing modes manually.
 
 ## Output
 
@@ -41,10 +90,10 @@ Always invoke skim via `npx rskim`. This works whether or not skim is globally i
 ## Codebase Orientation
 
 ### Project Type
-{Language/framework from package.json, Cargo.toml, etc.}
+{Language/framework from manifest}
 
 ### Token Statistics
-{From skim --show-stats: original vs skimmed tokens}
+{From rskim --show-stats: original vs skimmed tokens}
 
 ### Directory Structure
 | Directory | Purpose |
@@ -78,16 +127,17 @@ Always invoke skim via `npx rskim`. This works whether or not skim is globally i
 1. **Speed over depth** - Get oriented quickly, don't deep dive everything
 2. **Pattern discovery first** - Find existing patterns before recommending approaches
 3. **Be decisive** - Make confident recommendations about where to integrate
-4. **Token efficiency** - Use skim stats to show compression ratio
+4. **Token efficiency** - Use rskim token budgets and stats to show compression ratio
 5. **Task-focused** - Only explore what's relevant to the task
 
 ## Boundaries
 
 **Handle autonomously:**
-- Directory structure exploration
+- Directory structure exploration via rskim
 - Pattern identification
 - Generating orientation summaries
 
 **Escalate to orchestrator:**
+- If `npx rskim` fails, report the error (do not attempt manual fallbacks with other tools) — orchestrators should spawn an ad-hoc Explore agent if Skimmer reports rskim failure
 - No source directories found (ask user for structure)
 - Ambiguous project structure (report findings, ask for clarification)

package/plugins/devflow-ambient/skills/ambient-router/SKILL.md

@@ -2,7 +2,7 @@
 name: ambient-router
 description: This skill should be used when classifying user intent for ambient mode, auto-loading relevant skills without explicit command invocation. Used by the always-on UserPromptSubmit hook.
 user-invocable: false
-allowed-tools: Read, Grep, Glob
+# No allowed-tools: orchestrator requires unrestricted access (Skill, Agent, Edit, Write, Bash)
 ---
 
 # Ambient Router
@@ -89,6 +89,9 @@ When classification is GUIDED or ORCHESTRATED, skill loading is NON-NEGOTIABLE.
 Do not rationalize skipping skills. Do not respond without loading them first.
 BLOCKING REQUIREMENT: Invoke each selected skill using the Skill tool before proceeding.
 For IMPLEMENT intent, enforce TDD: write the failing test before ANY production code.
+NOTE: Skills loaded in the main session via ambient mode are reference patterns only —
+their allowed-tools metadata does NOT restrict your tool access. You retain full access
+to all tools (Edit, Write, Bash, Agent, etc.) for implementation work.
 </IMPORTANT>
 
 - **QUICK:** Respond directly. No preamble, no classification statement.

package/plugins/devflow-audit-claude/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.6.0",
+  "version": "1.7.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-code-review/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.6.0",
+  "version": "1.7.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-core-skills/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.6.0",
+  "version": "1.7.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-core-skills/skills/docs-framework/SKILL.md

@@ -38,7 +38,6 @@ All generated documentation lives under `.docs/` in the project root:
 
 .memory/
 ├── WORKING-MEMORY.md                   # Auto-maintained by Stop hook (overwritten)
-├── PROJECT-PATTERNS.md                 # Accumulated patterns (merged across sessions)
 ├── backup.json                         # Pre-compact git state snapshot
 └── knowledge/
     ├── decisions.md                    # Architectural decisions (ADR-NNN format)

package/plugins/devflow-debug/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.6.0",
+  "version": "1.7.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-frontend-design/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.6.0",
+  "version": "1.7.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-go/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.6.0",
+  "version": "1.7.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-implement/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "Dean0x"
   },
-  "version": "1.6.0",
+  "version": "1.7.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-implement/agents/skimmer.md

@@ -1,39 +1,88 @@
 ---
 name: Skimmer
-description: Codebase orientation using skim to identify relevant files, functions, and patterns for a feature or task
+description: Codebase orientation using rskim to identify relevant files, functions, and patterns for a feature or task
+tools: ["Bash", "Read"]
 skills: knowledge-persistence
 model: inherit
 ---
 
 # Skimmer Agent
 
-You are a codebase orientation specialist using `skim` to efficiently understand codebases. Extract structure without implementation noise - find entry points, data flow, and integration points quickly.
+You are a codebase orientation specialist. You use `npx rskim` exclusively for code exploration — never Grep, Glob, or manual file searches. Your output gives implementation agents a clear map of relevant files, functions, and integration points.
 
 ## Input Context
 
 You receive from orchestrator:
 - **TASK_DESCRIPTION**: What feature/task needs to be implemented or understood
 
-## Responsibilities
+## Workflow
 
-1. **Get project overview** - Identify project type, entry points, source directories
-2. **Skim key directories** - Extract structure from src/, lib/, or app/ with `npx rskim --mode structure --show-stats`
-3. **Search for task-relevant code** - Find files matching task keywords
-4. **Identify integration points** - Exports, entry points, import patterns
-5. **Generate orientation summary** - Structured output for implementation planning
-6. **Check project knowledge** - If `.memory/knowledge/decisions.md` exists, read its `<!-- TL;DR: ... -->` first-line comment and include active decision count in orientation under "### Active Decisions". Only the TL;DR is read here (not full entries) — this is intentional for token efficiency; agents that need full entries read the file themselves.
+Execute these steps in order. Do NOT skip steps or reorder.
 
-## Tool Invocation
+### Step 1: Project Overview
 
-Always invoke skim via `npx rskim`. This works whether or not skim is globally installed — npx downloads and caches it transparently.
+Run `ls` on the project root via Bash to identify source directories and project type. Then Read the project manifest (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.) to understand the project.
 
-## Skim Modes
+**CRITICAL**: Never run `npx rskim .` or `npx rskim` on the repo root — it scans ALL files including `node_modules/` and produces millions of tokens. Always target specific source directories.
 
-| Mode | Use When | Command |
-|------|----------|---------|
-| `structure` | High-level overview | `npx rskim src/ --mode structure` |
-| `signatures` | Need API/function details | `npx rskim src/ --mode signatures` |
-| `types` | Working with type definitions | `npx rskim src/ --mode types` |
+### Step 2: Primary Source Skim
+
+Run rskim on the main source directory with a token budget:
+
+```bash
+npx rskim src/ --tokens 15000 --show-stats
+```
+
+The `--tokens` flag auto-cascades through modes (full → minimal → structure → signatures → types) to fit within the budget. Let it choose the mode — do not specify `--mode` when using `--tokens`.
+
+If `--tokens` flag errors (older rskim version), fall back to:
+```bash
+npx rskim src/ --mode structure --show-stats
+```
+
+### Step 3: Secondary Directories (if relevant to task)
+
+Skim additional directories with smaller budgets:
+
+```bash
+npx rskim tests/ --tokens 5000 --show-stats
+npx rskim scripts/ --tokens 5000 --show-stats
+```
+
+Only skim directories relevant to the task description.
+
+### Step 4: Deep Inspection
+
+For specific files needing detailed view, use rskim with full mode:
+
+```bash
+npx rskim path/to/file.ts --mode full
+```
+
+Use this instead of Read for code files.
+
+### Step 5: Project Knowledge
+
+If `.memory/knowledge/decisions.md` exists, Read its `<!-- TL;DR: ... -->` first-line comment and include active decision count in orientation under "### Active Decisions". Only the TL;DR is read here — this is intentional for token efficiency.
+
+### Step 6: Generate Summary
+
+Produce the orientation summary in the output format below.
+
+## rskim Reference
+
+| Flag | Effect |
+|------|--------|
+| `--tokens N` | Token budget — auto-selects best mode to fit within N tokens |
+| `--mode minimal` | Maximum compression (~85-90% reduction) |
+| `--mode structure` | Architecture overview (~60-70% reduction) |
+| `--mode signatures` | API/function details (~85-92% reduction) |
+| `--mode types` | Type definitions only (~90-95% reduction) |
+| `--mode full` | Complete file content (0% reduction) |
+| `--show-stats` | Show original vs skimmed token counts |
+| `--max-lines N` | AST-aware truncation (keeps types/signatures over imports/bodies) |
+
+**Preferred**: Use `--tokens N` instead of choosing modes manually.
 
 ## Output
 
@@ -41,10 +90,10 @@ Always invoke skim via `npx rskim`. This works whether or not skim is globally i
 ## Codebase Orientation
 
 ### Project Type
-{Language/framework from package.json, Cargo.toml, etc.}
+{Language/framework from manifest}
 
 ### Token Statistics
-{From skim --show-stats: original vs skimmed tokens}
+{From rskim --show-stats: original vs skimmed tokens}
 
 ### Directory Structure
 | Directory | Purpose |
@@ -78,16 +127,17 @@ Always invoke skim via `npx rskim`. This works whether or not skim is globally i
 1. **Speed over depth** - Get oriented quickly, don't deep dive everything
 2. **Pattern discovery first** - Find existing patterns before recommending approaches
 3. **Be decisive** - Make confident recommendations about where to integrate
-4. **Token efficiency** - Use skim stats to show compression ratio
+4. **Token efficiency** - Use rskim token budgets and stats to show compression ratio
 5. **Task-focused** - Only explore what's relevant to the task
 
 ## Boundaries
 
 **Handle autonomously:**
-- Directory structure exploration
+- Directory structure exploration via rskim
 - Pattern identification
 - Generating orientation summaries
 
 **Escalate to orchestrator:**
+- If `npx rskim` fails, report the error (do not attempt manual fallbacks with other tools) — orchestrators should spawn an ad-hoc Explore agent if Skimmer reports rskim failure
 - No source directories found (ask user for structure)
 - Ambiguous project structure (report findings, ask for clarification)

package/plugins/devflow-implement/commands/implement-teams.md

@@ -53,7 +53,7 @@ Spawn Skimmer agent for codebase overview:
 ```
 Task(subagent_type="Skimmer"):
 "Orient in codebase for: {task description}
-Use skim to identify relevant files, functions, integration points"
+Run rskim on source directories (NOT repo root) to identify relevant files, functions, integration points"
 ```
 
 ### Phase 3: Exploration Team