@theihtisham/agent-shadow-brain 7.0.0 → 7.1.3

package/docs/WORKFLOW_INTEGRATION.md

@@ -0,0 +1,105 @@
+# Focused workflows and project skills
+
+Agent Shadow Brain 7.1.0 bundles practical guidance for coding agents. It helps the host select an appropriate workflow, avoid unnecessary extra work, and check the requested result. It does not call a model or run the task on its own. Your host agent supplies the reasoning, tools, permissions, and execution.
+
+## Choose a client and install
+
+Use Node 22.12+ within 22.x, Node 24.x, or Node 26+. Install the package, move to the project root, and preview the files:
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain
+shadow-brain skills install . --target codex
+shadow-brain skills install . --target codex --apply
+```
+
+| Target | Skill directory | Project instructions |
+| --- | --- | --- |
+| `codex` | `.agents/skills/<name>/SKILL.md` | `AGENTS.md` |
+| `claude-code` | `.claude/skills/<name>/SKILL.md` | `CLAUDE.md` |
+| `opencode` | `.opencode/skills/<name>/SKILL.md` | `AGENTS.md` |
+| `deepseek-harness` | `.dsh/skills/<name>/SKILL.md` | `AGENTS.md` |
+| `portable` (default) | `.agents/skills/<name>/SKILL.md` | `AGENTS.md` |
+
+Use a comma-separated target list or `--target all` for the four native layouts. Existing identical destinations are deduplicated. Prefer only the targets you use: some hosts can discover several compatible roots. Select a smaller catalog with `--skills shadow-workflow,shadow-debug`. `skills targets` prints the supported mappings; `skills show shadow-debug` prints the complete bundled skill.
+
+The managed project-instruction section points relevant tasks to the installed skills and defers to user and project constraints. Skill discovery remains a host feature: restart or reload the client if its documentation requires it. For DeepSeek Harness, install at its actual project root (nearest `.git` ancestor, or working directory if there is no repository). Enable the host's filesystem skill provider, registry and skill tool, plus agent-instruction context if you want the `AGENTS.md` pointer. This installer does not change host plugin configuration.
+
+Other clients can use the portable layout if they support it, or read an installed `SKILL.md` explicitly. An MCP-capable client can retrieve the same guidance through the tools below. There is no claim that every client automatically discovers these files.
+
+## What each skill contributes
+
+| Skill | Purpose |
+| --- | --- |
+| `shadow-workflow` | Understand the outcome and constraints, choose the relevant guidance, and scale planning and verification. |
+| `shadow-implement` | Inspect relevant code, make the requested change, and verify affected behavior. |
+| `shadow-debug` | Isolate a failure using evidence; fix it when requested; confirm the original failure is resolved. |
+| `shadow-review` | Report actionable findings with evidence; edit only when the requested scope includes fixes. |
+| `shadow-research` | Check relevant sources, separate facts from inference, and answer the user's question. |
+| `shadow-release` | Prepare and verify an artifact, perform an authorized release, and independently check the destination. |
+
+Skills keep trivial questions direct, respect planning/diagnosis/review-only requests, and avoid unrelated rewrites, audits, documents, and tests. They ask for missing input only when it materially blocks correct work. Prior authorization counts; a routine second approval is not required. Available memory can supply fallible context, but memory writes are not compulsory. A useful plan states actions and verification, not private reasoning transcripts.
+
+## Preview, updates, and conflicts
+
+Without `--apply`, installation performs no writes. The plan shows destination paths, content, actions, hashes, and warnings (`--json` gives the full structure). Application recomputes and validates the plan and checks existing content before changing files.
+
+Skills are allowlisted bundled files. Differing unowned files, locally edited managed files or blocks, malformed instruction markers, unsafe paths, and stale previews are rejected. Bytes outside the managed instruction block are preserved. A project-local `.shadow-brain/workflow-skills.json` receipt records ownership hashes so later package upgrades can distinguish managed content from local edits. Commit it with the installed skills if your team shares the installation.
+
+Managed updates save original files under `.shadow-brain/workflow-backups/`. Caught write errors trigger best-effort rollback where the files still match this attempt; the installer reports failures instead of silently overwriting concurrent edits. It uses an exclusive project installation lock. Process termination can leave a partial installation and lock; arbitrary concurrent editors are not transactional. Rerun preview after resolving a reported conflict. Do not delete an active lock. After an interrupted process, confirm no installer is running before manually removing an abandoned `.shadow-brain/workflow-skills.lock`.
+
+There is no force-overwrite or uninstall command. To remove the integration, review the receipt and installed paths, remove only the selected managed skill files and delimited instruction blocks, and preserve your own additions. Keep backups until the update has been checked. Do not remove a whole shared skills directory.
+
+The installer never changes global client settings, selects providers/models, reads authentication stores, starts hosts, or executes skill commands. Installing or upgrading the npm package itself does not install skills into projects.
+
+## Advisory request analysis
+
+```bash
+shadow-brain workflow analyze "Fix the failing CSV export" --json
+shadow-brain workflow analyze "Plan a storage migration; do not edit files" --json
+shadow-brain workflow analyze "Review this change" --type review --mode plan-only --json
+shadow-brain workflow analyze --request-file ./task.txt --type implement --complexity complex --json
+```
+
+Options are `--mode auto|plan-only|execute`, `--type auto|implement|debug|review|research|release`, and `--complexity auto|simple|complex`. Request files must be at most 64 KiB. The router returns task type, mode, relevant skills, bounded steps with completion checks, reasons, authorization categories, and limitations. It does not save requests or create plan files.
+
+Automatic classification is a deterministic English-language heuristic, not a language model. Ambiguous, quoted, complex negation, or non-English text may require explicit options and host interpretation. Its suggestions do not grant permission. `requiresAuthorization` identifies external-action categories for the host to check against the user's existing authorization, not an instruction to ask again. Explicit user boundaries remain authoritative even when an execution override is supplied.
+
+## Library and MCP
+
+```js
+import {
+  analyzeTask,
+  listBundledSkills,
+  getBundledSkill,
+  listWorkflowTargets,
+  planSkillInstall,
+  applySkillInstall,
+} from '@theihtisham/agent-shadow-brain';
+
+const workflow = analyzeTask('Diagnose the timeout without changing code');
+const catalog = listBundledSkills();
+const content = getBundledSkill('shadow-debug').content;
+const targets = listWorkflowTargets();
+const plan = planSkillInstall({ projectDir: process.cwd(), targets: ['codex'] });
+// When installation has been requested and the plan is acceptable:
+const installed = applySkillInstall(plan);
+```
+
+Plans and installation results are synchronous. An apply failure throws; do not treat it as a successful installation. Keep the plan unchanged between preview and apply. Public type exports describe the options and results.
+
+Existing Shadow Brain MCP connections expose two additional read-only tools:
+
+- `workflow_analyze`: `{ "request": "...", "mode": "auto", "taskType": "auto", "complexity": "auto" }`.
+- `workflow_skills`: `{}` lists names and descriptions; `{ "name": "shadow-debug" }` returns full guidance.
+
+These tools do not install files, execute tasks, or call providers. Skill file installation also does not automatically configure MCP or start the memory service. The existing memory tools remain separately available through an explicitly configured integration.
+
+## Compatibility evidence
+
+These layouts were checked against the official sources below on 2026-11-11. Automated tests validate package contents, installation, preservation, and advisory behavior. They do not establish that a particular running client loaded a skill or that a model followed every instruction.
+
+- [Codex skills documentation](https://learn.chatgpt.com/docs/build-skills): project `.agents/skills` discovery and skill frontmatter.
+- [Claude Code skills](https://code.claude.com/docs/en/skills): project `.claude/skills` and on-demand guidance.
+- [OpenCode skills](https://opencode.ai/docs/skills/): native and compatible roots.
+- [DeepSeek Harness filesystem skill provider](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/skill/skill-filesystem/README.md): roots, priority, project-root detection, one-level bundles, and required plugins.
+- [DeepSeek Harness project context](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/context/README.md): agent-instruction context.

package/docs/WORKSPACE.md

@@ -0,0 +1,111 @@
+# 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, project inventory, and recent activity. **Memories** lets you search and inspect a memory's recorded sources, review history, and links. **Graph** shows project membership, recording agents, and explicit links between memories. **Context** builds a pack for the task at hand. **Integrations** shows available client features and local checks. **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.
+
+## Follow live operations
+
+Open `/live` on the dashboard address. Select a session to follow its activity network and event timeline. The charts summarize matched, measured tool calls in the loaded window. The portal marks incomplete windows when older events have been dropped.
+
+The standalone MCP service measures its own session and tool boundaries. A host can explicitly report phases such as planning or verification, or tool start and end events from its own integration. The portal labels those events **Host-reported** and keeps them separate from measured timing.
+
+```bash
+shadow-brain activity report phase --project-id PROJECT_ID --session SESSION_ID --agent codex --phase verify
+shadow-brain activity tail --project-id PROJECT_ID
+```
+
+Use a shared `--correlation` ID on tool start and end reports. The end report also takes `--outcome` and `--duration-ms`. Use the previous tail result's `cursor` and `journalId` with `--cursor` and `--journal-id` to read the next page. Set `--db <path>` to use the journal next to a particular memory store.
+
+The local `activity-journal.json` retains the latest 500 events. It stores short labels, source, phase, tool name, outcome, and timing. Keep prompts, arguments, file paths, memory content, and credentials out of reports. A demo label identifies scripted sample events.
+
+## 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 excludes archived, contested, and superseded memories before ranking. It considers up to 200 eligible 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 and explicit links with their originating memory IDs. Distinct statements remain separate. A recorded contradiction is called out in the pack so the agent can check it.
+
+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, runtime controls, and annotation revision. A task can still recall an older relevant lesson.
+
+## Review and connect memories
+
+Open a memory from **Memories** or **Graph** to inspect its saved content, references, and review history. Set its review state to **Active**, **Archived**, or **Contested**. The review records your judgment. Check important claims against their sources.
+
+Use an explicit link to relate, support, contradict, or supersede another memory in the same project. For a supersession, choose the replacement first and the older memory second. A superseded memory stays out of context if its replacement disappears. Remove the supersession link to restore the older memory's prior review state.
+
+For CLI use, substitute the IDs shown in the workspace or the JSON output from `context-pack`.
+
+```bash
+shadow-brain curate show MEMORY_ID --project-id PROJECT_ID
+shadow-brain curate review MEMORY_ID contested --project-id PROJECT_ID --note "Check the current retry test"
+shadow-brain curate link REPLACEMENT_ID MEMORY_ID supersedes --project-id PROJECT_ID
+shadow-brain curate unlink LINK_ID --project-id PROJECT_ID
+```
+
+The commands return JSON. Write commands accept `--revision` to reject updates based on an older annotation revision. Use `--db <path>` for an explicit memory store and `--annotations <path>` to select a separate annotation file. By default the commands use `memory-annotations.json` next to the memory store.
+
+The annotation file holds up to 5,000 reviews, 5,000 links, and the latest 500 audit events, with a 16 MiB file limit. Notes are capped at 1,000 characters. The original `global.json` remains separate. Curation applies to context packs and automatic briefings. Memory inspection remains available for reviewing earlier records.
+
+## 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 | Shows live operations and serves dashboard activity updates and backlog. Turning it off also hides CLI activity tail output. |
+| `activityRecording` | On | Appends measured service activity and explicit host reports. Turning it off stops new records. Existing history remains available while live activity is enabled. |
+
+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
+
+Configure a compatible MCP client to launch `shadow-brain mcp --stdio`. The service offers nine read-only memory and workflow tools. When activity recording is enabled, it also records measured session and tool timing. The separate `activity_report` tool explicitly writes host-reported metadata to the journal. The service handles MCP messages without loading provider configuration. Use `--db <path>` and `--settings <path>` to point an isolated client at its own files.
+
+The MCP tools `context_pack` and `feature_flags` provide context assembly and current feature states. `context_pack` accepts `projectId`, optional `query`, `tokenBudget`, and `includeCrossProject`. Inspect or change reviews through the workspace or `curate` commands.
+
+The library exports `assembleContext`, `MemoryAnnotationsStore`, `FeatureSettingsStore`, and their types. Pass a recall source, current feature settings, and an annotation snapshot to `assembleContext`. Context assembly uses stored memories and recorded references without making model calls.
+
+The **Integrations** view checks the project skill files in a selected directory and shows runtime and storage status. Host-side skill discovery and MCP configuration are separate steps. DeepSeek Harness needs its filesystem skill and MCP client plugins enabled. [Skill integration guide](WORKFLOW_INTEGRATION.md)
+
+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/telemetry` | Read a page of journal events, with `project`, `cursor`, `journalId`, and `limit` options. |
+| `POST /api/workspace/activity-report` | Write an explicit host report with a project, session, agent, and event kind. |
+| `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.1.3.md

@@ -0,0 +1,40 @@
+# Agent Shadow Brain 7.1.3
+
+Version 7.1.3 connects memory review, the workspace graph, and the context handed to an agent. The new live operations portal shows recorded agent activity and tool timing.
+
+## Live operations
+
+Open `/live` on the dashboard address for the session list, activity network, charts, and event timeline. Measured activity comes from the local MCP service. Hosts can explicitly report task phases and tool spans. The portal labels the two sources and uses matched, measured calls for timing metrics.
+
+The shared local journal keeps the latest 500 metadata events. It tracks sequence and journal identity so readers can continue from a cursor and detect gaps or a restarted journal. `activityRecording` controls new records and `liveActivity` controls visibility. Both are enabled by default and can be changed with the other three runtime controls. Use `activity report` to send a host report and `activity tail` to inspect the journal.
+
+## Memory review and relations
+
+Open a memory in the workspace to see its content, recorded references, current review, and history. Set its state to active, archived, or contested. Record a same-project link of type related, supports, contradicts, or supersedes. Supersession links point from the replacement to the older memory.
+
+Context assembly filters inactive memories before ranking, preserves relevant relation and source provenance when collapsing duplicates, and labels recorded contradictions. If a replacement disappears, its older memory stays superseded until you remove the relation. Manual reviews and links record decisions to inspect against the underlying evidence.
+
+The `curate show`, `curate review`, `curate link`, and `curate unlink` commands use the same annotation store as the workspace. The store validates project identities, revisions, duplicate relations, and supersession cycles. It keeps an audit trail alongside the existing memory store.
+
+## Connect a client
+
+The workspace's Integrations view shows project skill-file presence, supported client capabilities, and local runtime and storage checks. Codex, Claude Code, OpenCode, and DeepSeek Harness can use their documented project skill layouts. Host-side discovery depends on client configuration.
+
+The standalone MCP service now runs over standard input and output.
+
+```bash
+shadow-brain mcp --stdio
+```
+
+Configure this command as the executable and arguments in a compatible client. The service exposes nine read-only memory, context, and workflow tools plus the explicit `activity_report` write tool. Activity recording uses a separate journal from the memory store. DeepSeek Harness needs its MCP client and filesystem skill plugins enabled. See the [workspace guide](../WORKSPACE.md) and [skill integration guide](../WORKFLOW_INTEGRATION.md).
+
+## Upgrade
+
+```bash
+npm install -g @theihtisham/agent-shadow-brain@7.1.3
+shadow-brain dash . --no-analysis
+```
+
+Existing memories retain schema version 1. Keep `global.json` and the separate `memory-annotations.json` when backing up your memory and review state. Follow the [7.0 migration notes](RELEASE_NOTES_v7.0.0.md) if you are upgrading from 6.x.
+
+This upgrade uses the maintainer-requested version **7.1.3**, published after 7.2.0. It is assigned the npm `latest` tag, but semver update tools may still prefer 7.2.0. Use the exact install command above.

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)