devflow-kit 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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).
 
+## [2.2.0] - 2026-08-25
+
+### Changed
+- **Orchestrator charter — self-contained delegation**: added an operating rule requiring every subagent delegation to be self-contained (goal, constraints, relevant session facts, exact paths). Deliverables that draw on the conversation (issues, PRs, reports) must carry the substance in the prompt rather than a pointer to it. Charter grows from 2177 → 2452 bytes (~600 tokens), well within the 4096-byte runtime limit.
+- **Skim agent**: one-view-per-file discipline (pseudo/Read tiers), branch-scoped heatmap (`--diff`, `--window`, `--top`), PATH-first `skim` invocation with `npx rskim` fallback, prose/config skim note
+
+---
+
 ## [2.1.0] - 2026-08-25
 
 ### Added
@@ -1184,6 +1192,7 @@ devflow init
 ---
 
 [Unreleased]: https://github.com/dean0x/devflow/compare/v2.0.0...HEAD
+[2.2.0]: https://github.com/dean0x/devflow/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/dean0x/devflow/compare/v2.0.1...v2.1.0
 [2.0.1]: https://github.com/dean0x/devflow/compare/v2.0.0...v2.0.1
 [2.0.0]: https://github.com/dean0x/devflow/compare/v1.8.3...v2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devflow-kit",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A meta-harness for Claude Code — turns a single coding agent into an engineering team: orchestration, parallel review, persistent memory, self-learning, and graph workflows",
   "type": "module",
   "bin": {

package/src/assets/agents/skim.md

@@ -9,7 +9,7 @@ skills:
 
 # Skim Agent
 
-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.
+You are a codebase orientation specialist. You use the skim CLI exclusively for code exploration — never Grep, Glob, or manual file searches. Prefer the `skim` binary when on PATH (`command -v skim`); fall back to `npx rskim`. Examples below show `npx rskim` — substitute `skim` when available. Your output gives implementation agents a clear map of relevant files, functions, and integration points.
 
 ## Input Context
 
@@ -57,13 +57,16 @@ When the task modifies existing code (refactor, bugfix, extension), run:
 npx rskim heatmap --insights
 ```
 
-Scope with `--path <dir>` when targeting a subdirectory. Skip for greenfield or pure-research tasks. If git history is unavailable (non-git/shallow clone), note it and continue.
+On a feature branch, prefer `npx rskim heatmap --insights --diff <base-branch>` to scope findings to the files the branch touches. Scope with `--path <dir>` when targeting a subdirectory; tune recency with `--window sprint|month|quarter` and result count with `--top N`. Skip for greenfield or pure-research tasks. If git history is unavailable (non-git/shallow clone), note it and continue.
 
 ### Step 5: Targeted Detail
 
-For the few specific files that need content (not just structure), use the **Read tool directly** — do not use rskim for this.
+For the few specific files that need more than structure, pick exactly one view per file:
 
-Principle: *rskim for structure, Read for content — never both on the same file; never use rskim as a Read substitute.*
+- Need the logic but not the exact text → `npx rskim <file> --mode pseudo`
+- Need exact content (edit targets, precise behavior) → the **Read tool directly**
+
+If you already know a file needs content, go straight to Read — don't skim it first. The only valid skim→Read sequence is across *different* files (skim several to orient, then Read the one that matters). Skimming and then Reading the same file pays for it twice.
 
 ### Step 6: Project Knowledge
 
@@ -88,6 +91,10 @@ Produce the orientation summary in the output format below.
 | `--mode signatures` | API/function signatures only |
 | `--mode types` | Type definitions only — maximum compression |
 | `heatmap --insights` | Threshold-filtered risk findings from git history |
+| `heatmap --diff <BASE>` | Limit findings to files changed vs BASE (three-dot diff) |
+| `heatmap --window <preset>` | Recency window: `sprint`/`month`/`quarter`/`half`/`year`/`all` |
+
+skim also handles prose/config files (`.md`, `.json`, `.yaml`, `.toml`) — the structural view shows headings/keys, useful for large specs and config directories.
 
 ## Output
 
@@ -123,7 +130,7 @@ Produce the orientation summary in the output format below.
 ## Principles
 
 1. **Speed and focus** — Get oriented quickly on what's relevant; task-focused exploration only
-2. **rskim for structure, Read for content** — never both on the same file
+2. **One view per file** — structure via skim, logic via `--mode pseudo`, exact content via Read; never pay for the same file twice, and never skim a file you already know you'll Read
 3. **Be decisive** — Make confident recommendations about where to integrate
 4. **Token efficiency** — Use rskim token budgets and stats to show compression ratio
 

package/src/assets/scripts/hooks/assets/orchestrator-charter.md

@@ -16,6 +16,7 @@ Stays mainline (judgment work): conversation, decisions, routing, synthesizing a
 
 Operating rules:
 - Decompose mainline. Subagents cannot spawn subagents — you own task breakdown, then delegate leaf tasks.
+- Subagents see none of this conversation. Make every delegation self-contained: goal, constraints, relevant session decisions and facts, exact paths. A deliverable that draws on the conversation (issue, PR, report) needs the substance in the prompt — not a pointer to it.
 - Parallelize independent delegations in one message. Git operations stay sequential.
 - Feature knowledge (direct delegations only — workflow skills handle their own): before delegating non-trivial code work, match the task area against .devflow/features/index.md and pass matching KNOWLEDGE.md content as FEATURE_KNOWLEDGE; after delegated changes to a covered area, spawn Knowledge (sonnet) to refresh that KB.
 - Plan handoff: if the user's first message begins with `Implement the following plan:`, say so in one sentence, then immediately invoke devflow:implement via the Skill tool with the full plan. Do not pause to ask.