@theihtisham/agent-shadow-brain 7.0.0 → 7.2.0

package/docs/WORKSPACE.md

@@ -0,0 +1,70 @@
+# Workspace guide
+
+Start the local workspace from your project directory.
+
+```bash
+shadow-brain dash . --no-analysis
+```
+
+The CLI binds to `127.0.0.1:7341` by default and opens the workspace. Use `--no-open` to open the printed address yourself, or `--port` to choose another port. `--no-analysis` starts the UI and API without background project analysis.
+
+**Overview** shows the memory count, projects and agents represented in the inventory, and recent activity. **Memories** supports project, category, agent, and text filters. **Graph** connects each memory to its project and recording agent. Select a node to inspect its detail. **Context** builds a pack for the task at hand. **Features** changes the runtime controls.
+
+The workspace uses up to 2,500 recent memories for its inventory and filter lists. Text search ranks matching records in the selected scope and returns up to 2,500 results. The graph displays up to 180 memories plus their project and agent nodes. The workspace indicates when it is showing a partial view.
+
+Visit `/advanced` for the previous dashboard and its existing tools. Its Features page links to the current controls.
+
+## Build context for the task
+
+Choose a project and enter a task or a few search terms. Review the selected memories, their recorded references, and the reasons entries were skipped before copying the pack.
+
+```bash
+shadow-brain context-pack "trace retry behavior in the importer" --project . --token-budget 1200 --json
+```
+
+The assembler considers up to 200 ranked candidates and selects up to 12 entries by default. The library supports a maximum of 30 entries. It groups exact content matches within a project after normalizing case and whitespace, keeps the highest-ranked representative, and carries forward bounded source references with their originating memory IDs. Distinct statements remain separate.
+
+The size limit applies to the complete Markdown, including labels and references. Long text can appear as a labeled excerpt. The assembler skips oversized entries and checks the remaining candidates. The token estimate is the rendered JavaScript string length divided by four, rounded up. It is a rough sizing guide because model tokenizers count text differently.
+
+Context stays within the selected project unless you enable `crossProjectContext` and explicitly request other projects using the workspace option, `--cross-project`, or the MCP/library option. Broader packs label each memory's project. Recorded references come from saved memory metadata. Check them against current sources before relying on a claim.
+
+Session-start briefings use the same assembler and budget. They respect the current task, project, allowed agents, and runtime controls. A task can still recall an older relevant lesson.
+
+## Change the runtime controls
+
+Set features in the workspace or through the CLI.
+
+```bash
+shadow-brain features list
+shadow-brain features set automaticBriefing off
+shadow-brain features set automaticBriefing on
+```
+
+| ID | Default | What it controls |
+| --- | --- | --- |
+| `contextAssembly` | On | Builds context packs, including the memory context used by session briefings. |
+| `crossProjectContext` | Off | Permits a context request to include other projects when the caller explicitly selects it. |
+| `automaticBriefing` | On | Generates session-start briefings for eligible agents. Turning it off also suppresses previously cached briefings. |
+| `liveActivity` | On | Serves the dashboard activity feed and delivers WebSocket activity events and backlog. Memory storage and other internal events continue operating. |
+
+Settings persist in `~/.shadow-brain/feature-settings.json` and take effect on the next relevant operation. The workspace writes validated changes and checks the settings revision before saving. If another client changes the settings first, review the refreshed values and try again. CLI commands accept `--settings <path>` for an explicitly selected file.
+
+## Integrate with a client
+
+The read-only MCP tools `context_pack` and `feature_flags` provide context assembly and current feature states. `context_pack` accepts `projectId`, optional `query`, `tokenBudget`, and `includeCrossProject`.
+
+The library exports `assembleContext`, `FeatureSettingsStore`, and their types. Pass a recall source and current feature settings to `assembleContext`. Context assembly uses stored memories and recorded references without making model calls.
+
+The local dashboard uses these HTTP endpoints.
+
+| Method and route | Purpose |
+| --- | --- |
+| `GET /api/workspace/overview` | Workspace totals, projects, recent memories, and current activity state. |
+| `GET /api/workspace/memories` | Filter and page through saved memories. |
+| `GET /api/workspace/graph` | Get project, agent, and memory nodes and their relationships. |
+| `POST /api/workspace/context` | Send a project ID, query, budget, and cross-project choice. |
+| `GET /api/workspace/activity` | Read the activity feed when enabled. |
+| `GET /api/workspace/features` | Read feature settings and their revision. |
+| `POST /api/workspace/features` | Send a boolean `patch` and optional `expectedRevision`. |
+
+Install the [bundled workflow skills](WORKFLOW_INTEGRATION.md) separately to give compatible clients task guidance.

package/docs/launch/RELEASE_NOTES_v7.1.0.md

@@ -0,0 +1,32 @@
+# Agent Shadow Brain 7.1.0
+
+This release adds focused task guidance and project skill installation on top of 7.0.0's durable memory and explained recall.
+
+## Changes
+
+- Six bundled skills: workflow selection, implementation, debugging, review, research, and release.
+- Project skill layouts for Codex, Claude Code, OpenCode, and DeepSeek Harness; portable files for other compatible clients.
+- Preview-first installation that preserves project instruction text, detects local edits, validates destinations and stale plans, records ownership, and backs up managed updates.
+- CLI skill catalog/install commands and advisory request analysis with explicit overrides.
+- Read-only MCP guidance tools and public library functions/types.
+
+The intended workflow is understand, plan when useful, execute authorized work, and verify. A small question stays a small answer. Plan-only, diagnosis-only, and review-only instructions keep their scope. No provider/model setup, credentials, new runtime dependencies, or global configuration changes are required.
+
+## Start
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@7.1.0
+# Run in the project root:
+shadow-brain skills install . --target codex
+shadow-brain skills install . --target codex --apply
+```
+
+Choose `claude-code`, `opencode`, `deepseek-harness`, `portable`, or `all` instead as appropriate. See the [integration guide](../WORKFLOW_INTEGRATION.md) for host requirements, updates, conflicts, and examples.
+
+## Verification and limits
+
+The release gate covers TypeScript, regression tests, installer preservation/failure scenarios, representative task-routing scenarios, skill frontmatter validation, and an installed npm tarball in a clean consumer project. CI runs on Windows and Linux with Node 22, 24, and 26. Final run counts and publication evidence are recorded in the release report.
+
+The router is a deterministic English-language heuristic; host interpretation and explicit options handle ambiguity. The package provides guidance, not autonomous task execution or authorization. Documented host layouts and automated installation tests do not prove that a running host discovered or followed a skill. DeepSeek Harness needs its skill/context plugins enabled.
+
+This is an additive 7.x release. No memory-store schema migration is introduced; retain the 7.0.0 upgrade guidance when coming from 6.x.

package/docs/launch/RELEASE_NOTES_v7.2.0.md

@@ -0,0 +1,24 @@
+# Agent Shadow Brain 7.2.0
+
+Version 7.2 makes it easier to see what agents have saved and choose what to hand to a new session. The default local workspace has five views for overview, memory search, the project and agent graph, context assembly, and feature controls. The previous dashboard remains available at `/advanced`.
+
+## What changed
+
+- Context packs rank memories for the selected project and task, collapse exact duplicates, retain recorded source provenance, and explain what fits the rendered budget. Cross-project context requires both a setting and explicit opt-in.
+- Session briefings use the same assembler. Cached briefings follow the current task and feature settings. Disabling automatic briefings suppresses both new and cached output.
+- Four persistent switches control context packs, cross-project access within context packs, automatic briefings, and dashboard activity. The settings store validates updates, detects revision conflicts, and replaces saved settings atomically.
+- The CLI adds `context-pack` and `features list|set`. MCP clients can call `context_pack` and `feature_flags`. Library consumers can import the assembler and settings store directly.
+- The README includes a conceptual memory-flow illustration and screenshots from the running workspace with synthetic data.
+
+## Start the workspace
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@7.2.0
+shadow-brain dash . --no-analysis
+```
+
+From a second terminal, run `shadow-brain context-pack "import retry behavior" --project . --token-budget 1200` to inspect what an agent would receive for that task.
+
+Memory storage keeps schema version 1. The six bundled skills and the existing skill install workflow remain available. If you are coming from 6.x, follow the [7.0 migration notes](RELEASE_NOTES_v7.0.0.md).
+
+[Workspace guide](../WORKSPACE.md) · [Skill integration guide](../WORKFLOW_INTEGRATION.md)

package/package.json

@@ -1,207 +1,111 @@
-{
-  "name": "@theihtisham/agent-shadow-brain",
-  "version": "7.0.0",
-  "description": "Local-first memory and coordination layer for AI coding agents. Shadow Brain stores source-backed project lessons, recalls them across Codex, Claude Code, Cursor, Cline, OpenCode, and other tools, generates resume briefings, audits memory quality, exports training/eval JSONL, and exposes CLI/API/MCP surfaces with zero telemetry.",
-  "main": "dist/index.js",
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "bin": {
-    "shadow-brain": "dist/cli.js",
-    "asb": "dist/cli.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "ts-node src/cli.ts",
-    "watch": "tsc --watch",
-    "test": "vitest run",
-    "lint": "tsc --noEmit",
-    "verify": "npm run build && npm test",
-    "pack:dry": "npm pack --dry-run",
-    "prepublishOnly": "npm run verify",
-    "test:package": "node tools/package-smoke.mjs"
-  },
-  "keywords": [
-    "ai",
-    "agent",
-    "brain",
-    "shadow",
-    "shadow-brain",
-    "agent-shadow-brain",
-    "subconscious",
-    "singleton-brain",
-    "global-brain",
-    "session-hook",
-    "agent-handoff",
-    "agent-firewall",
-    "mcp-security",
-    "prompt-injection",
-    "secret-scanning",
-    "auto-attach",
-    "claude-code",
-    "claude",
-    "cursor",
-    "cursor-ai",
-    "kilo-code",
-    "cline",
-    "opencode",
-    "codex",
-    "openai-codex",
-    "roo-code",
-    "rovodev",
-    "aider",
-    "copilot",
-    "github-copilot",
-    "windsurf",
-    "codeium",
-    "review",
-    "intelligence",
-    "mcp",
-    "mcp-server",
-    "model-context-protocol",
-    "lsp",
-    "language-server",
-    "llm",
-    "anthropic",
-    "openai",
-    "gemini",
-    "ollama",
-    "deepseek",
-    "turbo-quant",
-    "infinite-memory",
-    "hierarchical-memory",
-    "context-recall",
-    "context-injection",
-    "consensus-engine",
-    "collective-learning",
-    "cross-agent",
-    "cross-project",
-    "cross-session",
-    "sssp",
-    "self-evolution",
-    "swarm-intelligence",
-    "knowledge-graph",
-    "adversarial-defense",
-    "hallucination-defense",
-    "bug-prediction",
-    "pagerank",
-    "neural-mesh",
-    "multi-agent",
-    "agentic",
-    "agentic-ai",
-    "zero-config",
-    "auto-setup",
-    "dashboard",
-    "plugin-system",
-    "brain-export",
-    "code-analysis",
-    "developer-tools",
-    "ai-coding",
-    "ai-pair-programming",
-    "coding-assistant",
-    "smart-fix",
-    "health-score",
-    "pattern-memory",
-    "smart-cache",
-    "predictive-prefetch",
-    "code-dna",
-    "temporal-intelligence",
-    "fine-tuning",
-    "intent-engine",
-    "git-hooks",
-    "ci-cd",
-    "team-collaboration",
-    "developer-productivity",
-    "trending",
-    "viral",
-    "open-source",
-    "hive-mind",
-    "subagent-bridge",
-    "sabb",
-    "causal-chains",
-    "dream-engine",
-    "agent-reputation",
-    "swarm-debate",
-    "pre-mortem",
-    "branch-brain",
-    "attention-heatmap",
-    "token-economy",
-    "formal-verification",
-    "calibration-monitor",
-    "air-gap",
-    "e2e-encryption",
-    "voice-mode",
-    "brain-garden",
-    "pr-review",
-    "team-brain",
-    "brain-exchange",
-    "local-first",
-    "ollama",
-    "forgetting-curve",
-    "sleep-consolidation",
-    "live-brain",
-    "resume-pack",
-    "memory-quality",
-    "training-jsonl",
-    "source-backed-memory"
-  ],
-  "author": "ihtisham",
-  "license": "MIT",
-  "dependencies": {
-    "@anthropic-ai/sdk": "^1.8.0",
-    "chalk": "^4.1.2",
-    "chokidar": "^5.0.0",
-    "commander": "^12.1.0",
-    "conf": "^13.0.0",
-    "diff": "^5.2.0",
-    "execa": "^9.6.1",
-    "ink": "^4.4.1",
-    "inquirer": "^8.2.6",
-    "marked": "^18.0.2",
-    "ora": "^9.3.0",
-    "react": "^18.3.1",
-    "simple-git": "^4.0.2",
-    "ws": "^8.22.2",
-    "zod": "^4.6.7"
-  },
-  "devDependencies": {
-    "@types/diff": "^5.2.3",
-    "@types/inquirer": "^9.0.7",
-    "@types/node": "^22.19.0",
-    "@types/react": "^18.3.0",
-    "@types/ws": "^8.5.13",
-    "ts-node": "^10.9.2",
-    "typescript": "^6.0.3",
-    "vite": "^8.3.8",
-    "vitest": "^5.1.0"
-  },
-  "engines": {
-    "node": "^22.12.0 || ^24.0.0 || >=26.0.0"
-  },
-  "files": [
-    "dist/**/*",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE",
-    "docs/launch/RELEASE_CHECKLIST_v6.0.3.md",
-    "docs/launch/RELEASE_NOTES_v6.0.3.md",
-    "docs/launch/RELEASE_NOTES_v6.1.0.md",
-    "docs/launch/RELEASE_NOTES_v6.2.0.md",
-    "tools/export-resume-pack.mjs",
-    "tools/record-global-memory.mjs",
-    "docs/launch/RELEASE_NOTES_v7.0.0.md",
-    "docs/launch/RELEASE_CHECKLIST_v7.0.0.md"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ihtishaam-dev/agent-shadow-brain.git"
-  },
-  "bugs": {
-    "url": "https://github.com/ihtishaam-dev/agent-shadow-brain/issues"
-  },
-  "homepage": "https://github.com/ihtishaam-dev/agent-shadow-brain#readme"
-}
+{
+  "name": "@theihtisham/agent-shadow-brain",
+  "version": "7.2.0",
+  "description": "Local memory, focused skills, and a visual context workspace for coding agents. Explore memories, build project-scoped context, and control briefings across Codex, Claude Code, OpenCode, and DeepSeek Harness.",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "shadow-brain": "dist/cli.js",
+    "asb": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/cli.ts",
+    "watch": "tsc --watch",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "verify": "npm run build && npm test",
+    "pack:dry": "npm pack --dry-run",
+    "prepublishOnly": "npm run verify",
+    "test:package": "node tools/package-smoke.mjs"
+  },
+  "keywords": [
+    "ai",
+    "coding-agents",
+    "agent-memory",
+    "local-first",
+    "context",
+    "context-management",
+    "agent-skills",
+    "task-workflow",
+    "codex",
+    "claude-code",
+    "opencode",
+    "deepseek-harness",
+    "mcp",
+    "dashboard",
+    "knowledge-graph",
+    "developer-tools",
+    "cross-agent",
+    "recall",
+    "typescript",
+    "cli"
+  ],
+  "author": "ihtisham",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^1.8.0",
+    "chalk": "^4.1.2",
+    "chokidar": "^5.0.0",
+    "commander": "^12.1.0",
+    "conf": "^13.0.0",
+    "diff": "^5.2.0",
+    "execa": "^9.6.1",
+    "ink": "^4.4.1",
+    "inquirer": "^8.2.6",
+    "marked": "^18.0.2",
+    "ora": "^9.3.0",
+    "react": "^18.3.1",
+    "simple-git": "^4.0.2",
+    "ws": "^8.22.2",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/diff": "^5.2.3",
+    "@types/inquirer": "^9.0.7",
+    "@types/node": "^22.19.0",
+    "@types/react": "^18.3.0",
+    "@types/ws": "^8.5.13",
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.8",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "node": "^22.12.0 || ^24.0.0 || >=26.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/launch/RELEASE_CHECKLIST_v6.0.3.md",
+    "docs/launch/RELEASE_NOTES_v6.0.3.md",
+    "docs/launch/RELEASE_NOTES_v6.1.0.md",
+    "docs/launch/RELEASE_NOTES_v6.2.0.md",
+    "tools/export-resume-pack.mjs",
+    "tools/record-global-memory.mjs",
+    "docs/launch/RELEASE_NOTES_v7.0.0.md",
+    "docs/launch/RELEASE_CHECKLIST_v7.0.0.md",
+    "skills/**/*",
+    "docs/launch/RELEASE_NOTES_v7.1.0.md",
+    "docs/WORKFLOW_INTEGRATION.md",
+    "docs/assets/*.png",
+    "docs/WORKSPACE.md",
+    "docs/launch/RELEASE_NOTES_v7.2.0.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ihtishaam-dev/agent-shadow-brain.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ihtishaam-dev/agent-shadow-brain/issues"
+  },
+  "homepage": "https://github.com/ihtishaam-dev/agent-shadow-brain#readme"
+}

package/skills/shadow-debug/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: shadow-debug
+description: Diagnose and fix a reported failure using a reproducible symptom, a focused cause investigation, and regression verification. Use for broken behavior, errors, crashes, or failing checks.
+---
+
+# Diagnose and repair
+
+Honor diagnosis-only or analysis-only requests: report the evidence and likely correction without editing files. Continue into repair only when fixing the problem is within the requested scope.
+
+Establish the exact symptom, expected behavior, and smallest reproduction available from the request and project. Preserve data and rollback options proportional to the impact. Inspect relevant logs and source without exposing private values.
+
+Test a cause hypothesis against evidence before changing multiple layers. Distinguish the failing component from downstream symptoms. If a reproduction is unavailable, make the uncertainty explicit and use a bounded fixture that exercises the suspected path.
+
+Fix the cause with a coherent change, then rerun the original reproduction or the closest valid equivalent. Add a meaningful regression test when the failure could recur. Check adjacent behavior affected by the fix, then stop when the acceptance conditions hold.
+
+After repeated failures, use the new evidence to revise the hypothesis; do not repeat the same attempt indefinitely or silently reset user state. Report the remaining blocker if the original environment cannot be exercised. A mock, running process, successful build, or isolated fixture is not proof that the user's original scenario works.

package/skills/shadow-implement/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: shadow-implement
+description: Implement or improve an explicitly requested project feature while preserving existing behavior and limiting changes to the requested outcome. Use after the goal is understood; not for analysis-only or review-only requests.
+---
+
+# Implement the requested change
+
+Trace the existing behavior through the relevant entry point, data flow, and tests before choosing an implementation. Reuse established components and configuration. Turn the requested behavior into a small set of acceptance conditions, including compatibility constraints that matter.
+
+For a small edit, make it directly. For a larger change, order the work around dependencies and failure risks; preserve a working intermediate state where practical. Do not add architecture, infrastructure, configuration options, or supporting features just because they might be useful later.
+
+Keep unrelated user changes intact. Handle input validation and errors where they affect the actual feature. Make user-facing controls explain meaningful choices instead of implementation details.
+
+Verify the affected path with an observable before/after case. Run repository-required checks and targeted tests appropriate to the change. Inspect a produced artifact or running result when build success alone cannot establish correctness. Add regression tests for behavior that can plausibly break; avoid tests that only repeat the implementation.
+
+Report what now works, what was verified, and any material limitation. Do not publish or deploy unless the request or existing authorization includes that action. If delivery is authorized, continue through delivery and verify the destination.

package/skills/shadow-release/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: shadow-release
+description: Prepare and verify a requested package or application release, including artifact contents and destination checks. Publish only when the user's request or existing authorization includes publication.
+---
+
+# Release a verified artifact
+
+Identify the release target, version, source revision, existing authorization, and relevant project release instructions. Complete required build and behavior checks before publishing. Keep local validation, remote CI, packaging, and live publication as distinct evidence.
+
+Inspect the distributable contents and exclude personal state, credentials, temporary files, and development dependencies. Test the actual artifact in a clean consumer or representative destination when packaging can affect behavior. Record its integrity or revision so the reviewed artifact can be matched to the release.
+
+Use the already authorized destination and authenticated tooling. Do not inspect credential stores or ask the user to send private authentication values. If the service requires interactive authentication, let the user complete it directly and resume the same release. Do not repeat irreversible publication while a prior attempt is still processing; inspect remote state first.
+
+After publishing, verify the destination's version or revision and artifact integrity. Treat an accepted upload, queued build, or processing notice as pending until the artifact is actually available. Preserve rollback information; do not silently unpublish, overwrite a released version, or rewrite existing history.
+
+Report the release link, relevant validation, and any remaining availability limitation concisely. Do not create promotional posts, messages, recurring jobs, or unrelated announcements unless requested.

package/skills/shadow-research/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: shadow-research
+description: Resolve a technical or product question with relevant source evidence and an actionable conclusion. Use when current facts, compatibility, alternatives, or uncertain behavior must be researched before a decision.
+---
+
+# Research for a decision
+
+Define the decision or question the evidence must answer. Start with available project documentation and primary sources appropriate to the question. Verify version-sensitive claims against current official documentation or observed behavior. Keep quoted material short and distinguish source claims from inference.
+
+Follow leads only while they can change the conclusion. Compare options using the user's actual constraints, not an exhaustive feature inventory. Report disagreement, missing evidence, and whether results are documentation-backed, fixture-tested, or demonstrated in the target environment.
+
+Deliver the answer or recommendation with supporting links and practical limits. Research alone does not authorize modifying configuration, installing products, contacting others, or deploying changes. Continue into implementation only when it is part of the requested task.

package/skills/shadow-review/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: shadow-review
+description: Review a requested code change or implementation for actionable correctness, security, data-loss, and compatibility problems. Use for reviews or audits; keep review-only work read-only.
+---
+
+# Review for actionable defects
+
+Identify the requested review scope and read the relevant code plus its callers, assumptions, and tests. Prefer concrete defects with a reachable trigger and an observable consequence. Prioritize data loss, broken behavior, authorization mistakes, and compatibility regressions over speculative style preferences.
+
+Check whether a suspected issue is already prevented by the surrounding code or established contract. Where useful, reproduce it in an isolated fixture. Label uncertainty rather than reporting an unproven hypothesis as a confirmed defect.
+
+For each actionable finding, explain the trigger, consequence, affected location, and a proportionate correction. Do not pad the review with generic hardening lists. If there are no actionable findings, say so and identify only meaningful validation limits.
+
+Review-only requests do not authorize edits or publication. If the user also requests fixes, implement the supported corrections, rerun the affected checks, and separate verified fixes from unresolved findings.

package/skills/shadow-workflow/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: shadow-workflow
+description: Complete requested project work with proportionate planning, focused execution, and evidence of completion. Use for feature work, repairs, reviews, research, or releases; handle trivial questions and edits directly.
+---
+
+# Focused task workflow
+
+Identify the requested outcome, explicit limits, and what would demonstrate completion. Read applicable project instructions and inspect only the context needed for the task. Preserve the user's chosen tools, architecture, and existing work.
+
+## Match effort to the request
+
+- For a factual answer, translation, small formatting change, or obvious local edit, act directly. Do not manufacture a plan, tracking files, research, or a test suite.
+- For work with dependencies, uncertain behavior, several affected components, or consequential deployment, form a concrete plan before editing. Tie steps to observable outcomes and revise the plan when evidence changes it.
+- If the user requests planning or analysis only, stop after that deliverable. A request to plan and then implement authorizes continuing into implementation within the requested scope.
+- Ask only when a missing decision materially changes correctness, scope, or permission and cannot be resolved from available evidence. Carry forward existing authorization; do not repeatedly ask to do work already requested.
+
+When installed and available, load only the focused skill that helps: `shadow-implement`, `shadow-debug`, `shadow-review`, `shadow-research`, or `shadow-release`. These are separate catalog entries; use the client's skill loader or read their installed SKILL.md. If a focused skill is unavailable, proceed using this workflow and the project instructions. Do not load the entire collection for every request.
+
+## Execute and verify
+
+Use the smallest coherent change that fulfills the outcome. Follow project conventions and keep unrelated cleanup, new frameworks, extra dashboards, documentation sets, and speculative features outside scope. Do not silently change provider settings or install tools merely to follow this skill.
+
+Choose verification that could reveal a meaningful failure: a regression reproduction, affected tests, build checks, an actual artifact, or a visible result as appropriate. Once relevant checks pass, finish unless a new failure or unresolved concern justifies more work. Distinguish prepared, tested, deployed, and independently observed states.
+
+For complex work, existing Shadow Brain memories can help orient the task. Treat memory as fallible reference, verify it against current evidence, and do not copy private credentials or entire conversations into it. The optional `shadow-brain workflow analyze` command returns a heuristic workflow suggestion; the executing agent remains responsible for interpreting intent, permissions, and current evidence. It does not run the task or grant authority.
+
+## Communicate
+
+Keep progress updates brief and useful. End with the outcome, essential verification, and any real remaining blocker. Match requested detail; avoid repeated summaries and extra recommendations when the user only needs the completed result. Never claim checks, publication, or client integration that were not actually observed.
+
+Client and project permissions remain in force. These instructions do not authorize unrelated publication, destructive operations, external messages, credential access, or changes outside the requested project.