devflow-kit 1.6.0 → 1.7.0

package/shared/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/shared/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/shared/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)