@theihtisham/agent-shadow-brain 6.3.0 → 7.1.0

package/dist/workflow-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-cli.js","sourceRoot":"","sources":["../src/workflow-cli.ts"],"names":[],"mappings":"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"}

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/launch/RELEASE_CHECKLIST_v7.0.0.md

@@ -0,0 +1,24 @@
+# 7.0.0 release checklist
+
+## Build and behavior
+
+- Confirm package.json, lockfile root, CLI, update checker, MCP metadata, dashboard, README, and release notes agree on 7.0.0.
+- Run `npm ci --ignore-scripts` from a clean checkout, then `npm run verify` and `npm run lint`.
+- Verify independent-process writes survive, queued success follows persistence, failed changes remain retryable, external deletions are preserved, and invalid stores remain byte-for-byte unchanged.
+- Verify unrelated agent notes cannot boost corroboration and every score is finite and explained.
+- Run `npm audit --audit-level=high`; record counts with the validation date.
+- Run `npm run test:package`; it packs the build, installs into a fresh temporary consumer, imports the public API, tests both new CLI commands, and verifies configuration isolation.
+
+## Publish the reviewed artifact
+
+- Keep the original 6.3.0 tarball and exact source commit available for rollback comparison.
+- Review `npm pack --dry-run --json` and allowlisted contents. Exclude personal state, node_modules, tests, temporary outputs, and configuration files.
+- Commit the reviewed source and lockfile; push without rewriting existing remote history.
+- Pack once, compute SHA-512/integrity, and publish that exact tarball with `npm publish <tarball> --access public --ignore-scripts` after local npm login by its owner.
+- If npm requests browser authentication or a second factor, the user completes it directly. Never put authentication material into scripts, output, or chat.
+- Verify registry 7.0.0 and `latest`, package integrity, and a fresh downloaded tarball. Publish the matching GitHub tag/release and attach the verified package.
+- Confirm remote CI separately. Do not describe unrun OS/runtime combinations as tested.
+
+## Rollback
+
+Use the preserved pre-upgrade store backup and install the previous package version if required. Stop all writers before restoring data. Published npm versions cannot be overwritten; release a corrective patch rather than silently replacing 7.0.0. Do not unpublish or move the latest tag without an explicit rollback decision.

package/docs/launch/RELEASE_NOTES_v7.0.0.md

@@ -0,0 +1,44 @@
+# Agent Shadow Brain 7.0.0
+
+Release date: 2026-11-11. Development used Astra for planning/review and GPT-6.1 SoL for core implementation. These are development roles, not newly bundled AI model services.
+
+## What changed
+
+Concurrent agents now serialize memory commits and merge their pending additions, access changes, and registrations with the latest valid disk snapshot. Successful queued-write acknowledgements follow persistence. Failed changes remain pending for retry. Corrupt or future-schema stores produce explicit errors while preserving the original bytes.
+
+Scored recall ranks the full matching pool, reports matched keywords and supporting agent identities, uses creation-age recency, and handles malformed numeric values without emitting NaN. Corroboration requires matching normalized content in the same project and category. Repeated text from different agent identities is a heuristic; it does not establish independent fact checking.
+
+New CLI commands:
+
+```sh
+shadow-brain storage-health --json
+shadow-brain storage-health --db ./global.json --json
+shadow-brain recall-explain "release verification" --limit 5
+```
+
+The MCP `global_storage_health` tool exposes the active process's pending operations and latest storage error without starting or flushing a store. Existing `global_recall_scored` results include explanations. The library entry point exports GlobalBrain and associated types.
+
+Installation no longer runs automatic agent setup. CLI help, version, storage-health, and recall-explain do not load provider settings. Dashboard activity rows escape memory text. Diagnostic output no longer prints key fragments. Dependencies are updated and promotional automation is manual-only.
+
+## Compatibility and migration
+
+- Supported runtimes: Node 22.12+ within 22.x, 24.x, or 26+.
+- Back up the store and stop older writers before upgrade. The new protocol cannot coordinate with an old writer that ignores its lock.
+- Store schema remains version 1. Invalid stores must be repaired or restored explicitly; automatic reset is removed.
+- `writeSync` stages an in-memory change. Use `await sync()` for persistence. A queued `write()` resolves after synchronization. A false result means queue rejection or failed persistence; accepted failed operations remain retryable.
+- Recalls use the current process snapshot; a sync refreshes external changes. There is no instantaneous cross-process notification guarantee.
+- Lock waits are bounded (default five seconds, configurable with `lockTimeoutMs`). Locks are never removed merely because they are old. After an interrupted process, inspect the writer and store before manually removing an abandoned `.lock` file.
+- Atomic replacement protects against partial JSON visibility. This release does not claim power-loss durability on every filesystem or safe coordination on all network filesystems.
+- Scores are heuristic rankings. Revisit application-specific `minConfidence` thresholds.
+- New health timestamps refer to the current process, not a persisted lifetime history.
+- Dependency major upgrades can affect applications importing re-exported Zod APIs; consult the upstream Zod 4 and simple-git 4 migration notes.
+
+## Source provenance
+
+The original repository URL returned 404 during this upgrade. The source was recovered from public fork `shadrackohemeng/agent-shadow-brain` at commit `bec756e19647a11cad570f8ae3c363792de84856`, exactly matching npm 6.3.0's `gitHead`. The downloaded 6.3.0 tarball is retained separately as the comparison baseline. Original MIT licensing and history are preserved.
+
+## Validation
+
+The release gate requires type-check/build, full tests, cross-process storage regressions, npm audit, fresh-consumer tarball installation, CLI/library smoke checks, package-content review, and Astra review. Remote CI results and publication status are recorded separately; prepared artifacts are not evidence of publication.
+
+Upstream references: [Vitest migration](https://main.vitest.dev/guide/migration/), [simple-git changelog](https://github.com/steveukx/git-js/blob/main/simple-git/CHANGELOG.md), [Zod migration](https://zod.dev/v4/changelog).

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.