devworkspace 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/README.md +210 -104
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,15 @@
2
2
 
3
3
  All notable changes are documented here. This project follows [Semantic Versioning](https://semver.org/). Workspace schema changes are called out under **Breaking**.
4
4
 
5
+ ## [0.4.1] - 2026-11-03
6
+
7
+ ### Fixed
8
+ - **Integration Test Reliability in Clean Environments**:
9
+ - Automatically compile the CLI on-demand (`ensureCliBuilt`) in `tests/integration/mcp-stdio.test.ts` when running in clean CI runners or coverage workflows where `dist/cli/main.js` has not yet been built.
10
+ - **Documentation & Onboarding Clarity**:
11
+ - Rewrote `README.md` with a plain-English mental model, architecture flowchart, beginner-friendly quick start, and explicit separation of traditional file instructions from MCP integration.
12
+ - Documented tool invocation semantics, testing scope disclaimers, and system `PATH` configuration requirements.
13
+
5
14
  ## [0.4.0] - 2026-11-03
6
15
 
7
16
  ### Added
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # DevWorkspace
2
2
 
3
- A **project-local AI engineering layer** for existing repositories. DevWorkspace gives an AI coding agent (Claude Code first) a small, portable, evidence-backed memory of your project, a task and verification discipline, and safety rails, without moving your project, creating an account, or needing an API key.
3
+ DevWorkspace is a **local-first engineering memory and verification layer** for software repositories. It provides AI coding agents (such as Claude Code, OpenAI Codex, Cursor, GitHub Copilot, and Google Antigravity) with a small, evidence-backed model of your project's architecture, verification commands, and safety boundaries—without sending your code to a third-party service, creating an account, or requiring an API key.
4
4
 
5
5
  ```bash
6
6
  cd my-project
@@ -8,162 +8,268 @@ npx devworkspace init
8
8
  npx devworkspace analyze
9
9
  ```
10
10
 
11
- ## What problem does it solve?
11
+ ---
12
12
 
13
- AI coding sessions start cold. The agent re-discovers your architecture, re-reads the same files, forgets decisions, runs the wrong tests, and sometimes declares victory while the build is red. DevWorkspace stores *knowledge* (not code) in `.devworkspace/`, keeps it honest (provenance, confidence, staleness), and installs a thin set of instructions that make the agent load context progressively, classify work, verify it, and update memory sparingly.
13
+ ## What Problem Does It Solve?
14
14
 
15
- ## What it is not
15
+ AI coding sessions start cold. Agents repeatedly re-read the same directory trees, infer incorrect architectural assumptions, forget past decisions, run the wrong test suites, or claim tasks are complete while the build is failing.
16
16
 
17
- DevWorkspace is not an LLM, an IDE, a Git client, a vector database, a code-graph engine, a test framework, a model router, or a cloud service. It orchestrates tools that already exist:
17
+ DevWorkspace solves this by:
18
+ 1. **Storing durable knowledge, not code:** Captures facts, decisions, and verification contracts in `.devworkspace/`.
19
+ 2. **Keeping context honest:** Tracks evidence sources, confidence ratings, and staleness so outdated assumptions are flagged.
20
+ 3. **Establishing operating rules:** Injects progressive context loading, Git safety rules (preventing destructive resets), and verification gates into agent workflows.
18
21
 
19
- | Concern | Provided by |
20
- | --- | --- |
21
- | Structural code understanding | [Graphify](https://github.com/Graphify-Labs/graphify) |
22
- | Engineering workflows (spec, plan, build, test, review, ship) | [Agent Skills](https://github.com/addyosmani/agent-skills) |
23
- | Quality, simplification, debt review | [Ponytail](https://github.com/DietrichGebert/ponytail) |
24
- | Model routing (optional, not used in V1) | [OmniRoute](https://github.com/diegosouzapw/OmniRoute) |
25
- | Correctness | **Your tests** |
22
+ ---
26
23
 
27
- DevWorkspace decides *when and why* a workflow applies. Those projects provide *how*.
24
+ ## How It Works
28
25
 
29
- ## Requirements
26
+ ```mermaid
27
+ flowchart LR
28
+ subgraph Local ["Your Local Machine"]
29
+ Repo["Repository Code & Manifests"] --> DW["DevWorkspace (.devworkspace/)"]
30
+ DW -->|"MCP stdio tools"| Agent["AI Coding Agent"]
31
+ DW -->|"Markdown instructions"| Agent
32
+ Agent -->|"Execute verification"| Gate["Tests, Lint & Typecheck"]
33
+ end
34
+ subgraph Cloud ["External AI Provider"]
35
+ Agent -.->|"Context in prompts"| Model["Cloud LLM (Anthropic / OpenAI / Google)"]
36
+ end
37
+ ```
30
38
 
31
- Node.js **20.11 or newer**. Works on Windows, macOS and Linux. Git is optional but strongly recommended.
39
+ 1. **Discover & Record:** Reads package manifests, configs, and file structure offline to construct a deterministic testing contract (`commands.json`) and discovery report.
40
+ 2. **Equip the Agent:** Exposes project context either via the local **Model Context Protocol (MCP)** server or via **file-based instruction blocks** (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`).
41
+ 3. **Enforce Verification:** Holds the agent accountable to your real test suites, linters, and typecheckers before marking work complete.
32
42
 
33
- ## Install
43
+ ---
34
44
 
35
- ```bash
36
- npx devworkspace init # no install needed
37
- # or
38
- npm install -g devworkspace
39
- devworkspace init
40
- ```
45
+ ## Quick Start
41
46
 
42
- ## Quick start
47
+ ### Prerequisites
48
+ Node.js **20.11 or newer**. Works on Windows, macOS, and Linux. Git is strongly recommended.
43
49
 
50
+ ### Step 1: Initialize the Workspace
44
51
  ```bash
45
52
  cd my-project
46
- npx devworkspace init # safe local setup; creates .devworkspace/
47
- npx devworkspace analyze # deterministic discovery + onboarding prompt
53
+ npx devworkspace init
48
54
  ```
55
+ Creates `.devworkspace/` with a nested `.gitignore` for machine-local state. It never modifies your source files and is safe to run multiple times.
56
+
57
+ ### Step 2: Analyze Project Structure & Testing Contract
58
+ ```bash
59
+ npx devworkspace analyze
60
+ ```
61
+ Scans dependencies, frameworks, entry points, and scripts. Generates detected facts and your project's verification contract.
62
+
63
+ ### Step 3: Connect Your Coding Agent
64
+ Choose the integration method that fits your agent (both can coexist safely):
49
65
 
50
- Optionally install the helper tools in one command (it shows what it will do first):
66
+ - **Option A: Model Context Protocol (MCP)** — Recommended for Claude Code, Codex, and Antigravity:
67
+ ```bash
68
+ npx devworkspace setup --agent claude-code
69
+ ```
70
+ - **Option B: File-Based Instructions** — For Cursor, Copilot, Codex, and Claude:
71
+ ```bash
72
+ npx devworkspace agent install --agent all
73
+ ```
51
74
 
75
+ ### Step 4: Verify Workspace Readiness
52
76
  ```bash
53
- npx devworkspace setup --integrations --dry-run
54
- npx devworkspace setup --integrations --yes
77
+ npx devworkspace doctor
55
78
  ```
79
+ Checks workspace health, instruction files, and testing contract consistency. When it reports `Core workspace: READY`, your project is ready for development.
56
80
 
57
- Then:
81
+ ---
58
82
 
59
- 1. Open `.devworkspace/analysis/onboarding-prompt.md`.
60
- 2. **Paste it into Claude Code** (or Claude in VS Code) in this project.
61
- 3. Let Claude finish and verify the onboarding. It inspects the real repository, runs `devworkspace agent install`, writes concise knowledge, checks the testing contract and reports unknowns and warnings.
62
- 4. Run `npx devworkspace doctor`. It should say `READY`.
83
+ ## Connecting Your Agent: Two Approaches
63
84
 
64
- `analyze` does **not** call an AI. A CLI cannot drive an existing Claude chat, so DevWorkspace does the deterministic part itself and hands the reasoning part to Claude through a prompt you paste.
85
+ DevWorkspace supports two ways to equip AI coding agents with project context. You can use either or both:
65
86
 
66
- ## Integrations (Graphify, Agent Skills, Ponytail)
87
+ | Capability | Approach A: Model Context Protocol (MCP) | Approach B: File-Based Instructions |
88
+ | --- | --- | --- |
89
+ | **How it works** | Runs a local stdio server exposing structured tools | Injects managed Markdown sections into instruction files |
90
+ | **Target files** | `.mcp.json`, `mcp.json`, `.antigravity/mcp.json` | `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, Copilot instructions |
91
+ | **Context retrieval** | Agent invokes tools directly (`get_task_context`, etc.) | Agent reads rules and runs CLI commands (`devworkspace context`) |
92
+ | **Best suited for** | Claude Code, OpenAI Codex, Google Antigravity | Cursor, GitHub Copilot, Codex, Claude Code |
93
+ | **CLI command** | `devworkspace setup --agent <name>` | `devworkspace agent install --agent <name>` |
67
94
 
68
- `devworkspace setup --integrations` installs and **verifies** them; `devworkspace integrations status` re-checks the real state at any time; `devworkspace doctor` reports core workspace health and integration health separately. Only project-local steps run without `--yes`; installing the Graphify tool for your user, user-scope installs and registry packages need `--yes`. Existing `CLAUDE.md`, `.claude` settings and skills are protected and restored if a tool would damage them. Some tools need a Claude Code restart afterwards, and that is reported as `RESTART_REQUIRED` rather than success. Details, scopes, limits and what was verified live: [docs/integrations.md](docs/integrations.md).
95
+ ### Seamless Coexistence
96
+ Both approaches can be used simultaneously in the same repository. DevWorkspace uses distinct HTML comment markers:
97
+ - **Standard CLI rules:** `<!-- devworkspace:start -->` ... `<!-- devworkspace:end -->`
98
+ - **MCP instructions:** `<!-- devworkspace-mcp:start -->` ... `<!-- devworkspace-mcp:end -->`
69
99
 
70
- ## Model Context Protocol (MCP) Server
100
+ Neither command will overwrite or interfere with the other, and custom developer notes outside the markers are preserved byte-for-byte.
71
101
 
72
- DevWorkspace includes a local-first Model Context Protocol (MCP) server so AI coding agents can retrieve project architecture, role-based task context, and file metadata automatically:
102
+ ---
103
+
104
+ ## Model Context Protocol (MCP) Integration
105
+
106
+ DevWorkspace includes a local-first Model Context Protocol (MCP 2024-11-05) server that enables compatible AI agents to query repository context dynamically over standard input/output (stdio).
107
+
108
+ ### Agent Configuration Commands
73
109
 
74
110
  ```bash
75
- # Configure Claude Code (.mcp.json + CLAUDE.md)
76
- devworkspace setup --agent claude-code
111
+ # Configure Claude Code (.mcp.json and CLAUDE.md)
112
+ npx devworkspace setup --agent claude-code
77
113
 
78
- # Configure OpenAI Codex (mcp.json + AGENTS.md)
79
- devworkspace setup --agent codex
114
+ # Configure OpenAI Codex (mcp.json and AGENTS.md)
115
+ npx devworkspace setup --agent codex
80
116
 
81
- # Configure Google Antigravity (.antigravity/mcp.json + rules)
82
- devworkspace setup --agent antigravity
117
+ # Configure Google Antigravity (.antigravity/mcp.json and .antigravity/rules)
118
+ npx devworkspace setup --agent antigravity
83
119
 
84
- # Preview configuration without writing files
85
- devworkspace setup --agent claude-code --check
120
+ # Configure all supported MCP agents at once
121
+ npx devworkspace setup --agent all
86
122
 
87
- # Run the local stdio MCP server directly
123
+ # Preview configuration changes without writing files (dry run)
124
+ npx devworkspace setup --agent claude-code --check
125
+
126
+ # Run the stdio MCP server directly
88
127
  devworkspace mcp serve
89
128
  ```
90
129
 
91
- MCP runs strictly over stdio, opens zero network ports, enforces workspace boundaries, redacts secrets, and operates without third-party cloud services or LLM API keys. Full guide: [docs/mcp.md](docs/mcp.md).
130
+ ### Available MCP Tools
131
+
132
+ Once configured, the following tools are available to the agent:
133
+
134
+ 1. **`get_project_overview`**: Returns the detected language stack, UI/backend frameworks, context health, and verification contract capabilities. Call at the start of a session or when exploring repository architecture.
135
+ 2. **`get_task_context`**: Generates progressive, role-sliced context tailored to specific requests (`explorer` for entry points, `tester` for test contracts, `reviewer` for ADRs and security rules). Preserves critical safety rules for all queries.
136
+ 3. **`get_file_context`**: Reads workspace-relative files bounded to 32KB per call with associated knowledge facts. Enforces path containment and automatically blocks credential files.
137
+
138
+ ### Important Notes on MCP Usage
139
+
140
+ - **Tool Invocation Depends on the Agent:** Registering the MCP server makes tools *available* to your coding agent. Whether and when the agent invokes a tool depends on the user's prompt, the agent's internal system prompt, and the model's decision-making. You can prompt the agent directly: *"Use get_project_overview to inspect this project"* or *"Call get_task_context for this bug fix"*.
141
+ - **Automated Tests vs. Live Agent Sessions:** DevWorkspace's MCP server and stdio transport are verified with automated subprocess integration and protocol test suites. However, interactive tool calling in proprietary desktop or terminal sessions (such as closed GUI builds of Claude Code, Codex, or Antigravity) has not been tested in live interactive client sessions and depends on each client's specific implementation.
142
+ - **PATH Requirement:** Generated configurations specify `"command": "devworkspace"`. Ensure `devworkspace` is in your environment `PATH` (e.g. `npm install -g devworkspace`). If running locally without global binaries, change the command in `.mcp.json` / `mcp.json` / `.antigravity/mcp.json` to `"npx"` with arguments `["-y", "devworkspace", "mcp", "serve"]`.
143
+
144
+ Full MCP technical manual and debugging options: [docs/mcp.md](docs/mcp.md).
92
145
 
93
- ## Daily workflow
146
+ ---
94
147
 
95
- Just talk to Claude:
148
+ ## Daily Workflow
96
149
 
97
- > Fix the quotation email bug.
98
- > Add Responsible Person to Leads.
99
- > Explain how authentication works.
150
+ When working with an AI agent in your repository:
100
151
 
101
- The installed instructions tell Claude to classify the request and apply a proportionate workflow. A question is read-only and runs no tests. A bug gets a regression test, a fix, and the verification your testing contract requires. A refactor records a test baseline first. You can override at any time: *"only explain"*, *"don't commit"*, *"don't run e2e"*. Overrides are honoured and recorded.
152
+ > *"Fix the invoice total rounding error in the billing service."*
153
+ >
154
+ > *"Add supplier management REST API endpoints."*
155
+ >
156
+ > *"Explain how tenant isolation middleware works."*
102
157
 
103
- Useful commands any time:
158
+ The installed instructions direct the agent to follow a proportionate workflow:
159
+ - **Questions:** Read-only inspection; runs no tests.
160
+ - **Bug fixes:** Write a regression test first, implement the fix, and run verified checks.
161
+ - **Refactoring:** Establish a passing test baseline before making modifications.
162
+ - **Explicit constraints:** Constraints like *"only explain"*, *"don't commit"*, or *"no e2e"* are strictly respected.
163
+
164
+ ### Common Daily Workflow Commands
165
+
166
+ For everyday development with an AI agent:
104
167
 
105
168
  ```bash
106
- devworkspace status # health, branch, knowledge, active tasks, verification commands
107
- devworkspace context # what DevWorkspace believes (facts, decisions, testing contract)
108
- devworkspace refresh # re-check knowledge against the repository; mark stale items
109
- devworkspace doctor # check workspace, integrations, security, portability
169
+ devworkspace status # Inspect workspace health, active tasks, and verification checks
170
+ devworkspace context --for "<task>" # Retrieve role-tailored context for a specific request
171
+ devworkspace doctor # Run diagnostic and portability checks
172
+ devworkspace refresh # Re-check repository evidence after pulling or large edits
110
173
  ```
111
174
 
112
- ## Commands
113
-
114
- | Command | Purpose |
115
- | --- | --- |
116
- | `init` | Create `.devworkspace/` (idempotent, never touches source) |
117
- | `setup` | One-command setup: initialize workspace, discover commands, verify diagnostics, optionally install integrations (`--integrations`) |
118
- | `integrations` | `status` (observed, never assumed) and `repair` |
119
- | `analyze` | Deterministic discovery; writes `discovery.json`, testing contract, onboarding prompt |
120
- | `agent install` | Add managed instruction blocks for your coding agent (`--agent claude\|codex\|cursor\|copilot\|all`) |
121
- | `agent list` | Show supported and detected coding agent integrations and their capabilities |
122
- | `status` | Concise overview, read-only (`--deep` also runs the integration health checks; `--json` for tooling) |
123
- | `doctor` | Health, security and portability checks (`--fix`, `--strict`, `--json`) |
124
- | `refresh` | Incremental staleness check; writes a refresh prompt when AI re-validation is needed |
125
- | `context` | Show stored knowledge (`--topic` filters facts and the testing contract; safety rules are always shown; `--full`) |
126
- | `fact` | `add` / `verify` / `remove` / `list` project knowledge with provenance |
127
- | `feature` | `list` / `show` / `validate` / `add` feature-level map connecting frontend, backend, database and tests |
128
- | `graph` | `status` and `trace` bounded knowledge-graph navigation with node and edge verification |
129
- | `task` | `new` / `list` / `show` / `status` / `update` / `run` / `verify` / `tests` / `attest` with a package-aware completion gate |
130
- | `testenv` | `declare` / `list` / `revoke` a test environment so database-touching checks may run (local, never committed) |
131
- | `decision` | Append-only, human-readable decision records |
132
- | `session` | Save short session summaries (never transcripts) |
133
- | `export` / `import` | Move portable knowledge between machines safely |
134
- | `reset` | Delete `.devworkspace/` to start fresh (`--yes` to confirm, `--include-agent-files` to also remove managed agent instruction blocks/skills) |
135
- | `migrate` | Upgrade workspace files to the current schema, with backups |
136
- | `mcp` | Local-first Model Context Protocol server (`serve`) and agent setup (`setup`) |
137
-
138
- Global flags: `--json`, `--cwd <dir>`, `--dry-run` (where it applies), `--debug`, `--no-color`, `--ascii`.
139
-
140
- **Exit codes:** `0` success · `1` failure · `2` usage error · `3` warnings (only with `--strict` on `status`/`doctor`) · `130`/`143` interrupted. Integrations that are not installed are *warnings*, never failures, so CI can use `devworkspace doctor` and fail only on real problems.
175
+ ### Command Reference
141
176
 
142
- ## Portability
177
+ | Command | Summary | Guide |
178
+ | --- | --- | --- |
179
+ | `init` | Create `.devworkspace/` in the project (safe to re-run) | [Getting Started](docs/getting-started.md) |
180
+ | `setup` | One-command setup: initialize, discover contracts, configure agents | [Getting Started](docs/getting-started.md) |
181
+ | `analyze` | Deterministic repository discovery and onboarding analysis | [Architecture](docs/architecture.md) |
182
+ | `status` | Concise health, Git branch, knowledge, and verification overview | [Getting Started](docs/getting-started.md) |
183
+ | `doctor` | Workspace, security, portability, and integration diagnostics | [Troubleshooting](docs/troubleshooting.md) |
184
+ | `context` | Task-aware context retrieval with optional role slicing | [Task Routing](docs/routing.md) |
185
+ | `refresh` | Re-check repository evidence and mark stale knowledge | [Knowledge Model](docs/knowledge.md) |
186
+ | `task` | Engineering task tracking with completion verification gate | [Testing Contract](docs/testing.md) |
187
+ | `agent` | Manage agent instructions (`agent install`, `agent list`) | [Agent Integrations](docs/agents.md) |
188
+ | `mcp` | Stdio Model Context Protocol server (`serve`) and agent setup (`setup`) | [MCP Guide](docs/mcp.md) |
189
+ | `integrations` | Inspect and repair optional helper tools (Graphify, Skills, Ponytail) | [Integrations](docs/integrations.md) |
190
+ | `fact` | Record, verify, list, or remove project facts with provenance | [Knowledge Model](docs/knowledge.md) |
191
+ | `feature` | End-to-end feature map tracing across routes, services, and tests | [Getting Started](docs/getting-started.md) |
192
+ | `graph` | Inspect and trace Graphify knowledge graphs | [Integrations](docs/integrations.md) |
193
+ | `decision` | Append-only architectural decision records (ADRs) | [Architecture](docs/architecture.md) |
194
+ | `session` | Record concise session summaries (never transcripts) | [Getting Started](docs/getting-started.md) |
195
+ | `testenv` | Declare local test environment for database-touching checks | [Testing Contract](docs/testing.md) |
196
+ | `export` | Export portable project knowledge to a bundle | [Portability](docs/portability.md) |
197
+ | `import` | Safely import an export bundle without silent overwrites | [Portability](docs/portability.md) |
198
+ | `reset` | Reset `.devworkspace/` (optional `--include-agent-files`) | [Getting Started](docs/getting-started.md) |
199
+ | `migrate` | Upgrade workspace files to current schema with backups | [Getting Started](docs/getting-started.md) |
200
+
201
+ Global flags supported across commands: `--json`, `--cwd <dir>`, `--dry-run`, `--debug`, `--no-color`, `--ascii`.
202
+
203
+ Exit codes: `0` success · `1` failure · `2` usage error · `3` warnings (with `--strict`) · `130`/`143` interrupted.
204
+
205
+ ---
206
+
207
+ ## Security, Privacy & Data Transmission
208
+
209
+ DevWorkspace enforces defense-in-depth safety controls:
210
+
211
+ ### Local DevWorkspace Protections
212
+ - **Zero Network Listeners:** DevWorkspace never opens HTTP or TCP ports. MCP runs strictly over local stdio child processes.
213
+ - **No Telemetry or Cloud Accounts:** DevWorkspace does not collect analytics or transmit data to DevWorkspace servers.
214
+ - **Credential Protection:** Credential files (`.env*`, `*.pem`, `*.key`, `id_rsa*`, tokens, keystores) are barred from reads. If an allowed source file contains API keys or tokens, patterns are automatically masked with `[REDACTED:<type>]`.
215
+ - **Workspace Boundary Enforcement:** Paths are validated with canonical checks (`resolveInside`) and symlink escape verification (`assertNoSymlinkEscape`). Directory traversal (`..`) and absolute paths are rejected.
216
+ - **Prompt-Injection Defense:** All retrieved context is demarcated with `=== BEGIN UNTRUSTED DEVWORKSPACE CONTEXT ===` headers, instructing the agent to treat repository content as untrusted evidence rather than executable instructions.
143
217
 
144
- Commit `.devworkspace/` (machine-local state in `.devworkspace/local/` is ignored by a nested `.gitignore`). On another computer: clone, then `devworkspace doctor`. Project identity is a random ID in `project.json`, never a path, so moving `D:\Company\CRM` to `C:\Projects\CRM` changes nothing. Details: [docs/portability.md](docs/portability.md).
218
+ ### AI Provider Notice
219
+ When an AI coding agent invokes DevWorkspace MCP tools or reads project files, that context enters the agent's context window and is transmitted to the external cloud LLM provider powering that agent (such as Anthropic, OpenAI, or Google). DevWorkspace governs what leaves your local files, while your AI provider's terms and privacy policies govern data processed in their cloud.
220
+
221
+ Full security and threat model: [docs/security.md](docs/security.md).
222
+
223
+ ---
224
+
225
+ ## Ecosystem & Helper Tools
226
+
227
+ DevWorkspace decides *when and why* engineering workflows apply. It can optionally orchestrate external helper tools:
228
+
229
+ | Concern | Tool | Status |
230
+ | --- | --- | --- |
231
+ | Structural code understanding | [Graphify](https://github.com/Graphify-Labs/graphify) | Optional integration (`setup --integrations`) |
232
+ | Engineering skill workflows | [Agent Skills](https://github.com/addyosmani/agent-skills) | Optional integration (`setup --integrations`) |
233
+ | Code quality & debt review | [Ponytail](https://github.com/DietrichGebert/ponytail) | Optional integration (`setup --integrations`) |
234
+ | Correctness & verification | **Your test suites** | Discovered deterministically in `commands.json` |
235
+
236
+ Details on scopes, prerequisites, and integration health checks: [docs/integrations.md](docs/integrations.md).
237
+
238
+ ---
239
+
240
+ ## Portability
145
241
 
146
- ## Security and privacy
242
+ Commit `.devworkspace/` to your version control system (machine-local files in `.devworkspace/local/` are ignored automatically). On another workstation, clone the repository and run `npx devworkspace doctor`. Project identity is managed via a UUID in `project.json` rather than hardcoded file paths, so repository paths can change without breaking project state. Full guide: [docs/portability.md](docs/portability.md).
147
243
 
148
- - Credential files (`.env*`, keys, `credentials.*`, …) are **never read**; only their presence is recorded. Secret-looking values are refused by every write path and redacted from logs.
149
- - Repository content is treated as **untrusted data**, and the generated instructions say so, to resist prompt injection.
150
- - Subprocesses use argument arrays, never a shell. Imports are validated before anything is written.
151
- - DevWorkspace itself sends nothing anywhere and has no telemetry. Generated prompts will, of course, cause *your chosen AI agent* to read repository files.
244
+ ---
152
245
 
153
- Details: [docs/security.md](docs/security.md).
246
+ ## Limitations
154
247
 
155
- ## Limitations (V1)
248
+ - **Language Scope:** Manifest and command discovery supports Node.js, Python, Go, Rust, Java, and PHP projects.
249
+ - **Client Environments:** Standard stdio protocol handling is verified via automated tests, but live interactive invocation depends on individual third-party agent desktop or CLI releases.
250
+ - **Model Prerogative:** MCP tool availability does not force an agent to invoke a tool; invocation depends on model planning and prompt specificity.
251
+ - **Integration Prerequisites:** Integrations like Graphify require Python 3.10+ or `uv` and explicit user authorization (`--yes`).
156
252
 
157
- - Multi-agent support includes typed adapters for Claude Code, OpenAI Codex (`AGENTS.md`), Cursor (`.cursor/rules` and `.cursorrules`), and GitHub Copilot (`.github/copilot-instructions.md`).
158
- - Integration setup needs prerequisites (Python 3.10+ or uv for Graphify; the Claude Code CLI for native plugins, otherwise portable skills with fewer capabilities) and sometimes your approval. It was not run end to end against GitHub on macOS/Linux; see the verification notes in [docs/integrations.md](docs/integrations.md).
159
- - DevWorkspace does not build Graphify's graph (that uses the model) or uninstall anything.
160
- - Deep analysis is not attempted for any language; discovery covers manifests, structure and commands for Node, Python, Go, Rust, Java and PHP projects.
161
- - The routing classifier is a keyword heuristic used to *propose* a type. The agent decides.
162
- - Token savings are not claimed. See [docs/benchmarking.md](docs/benchmarking.md) for how to measure them.
253
+ ---
163
254
 
164
255
  ## Documentation
165
256
 
166
- [Getting started](docs/getting-started.md) · [Architecture](docs/architecture.md) · [Agents](docs/agents.md) · [Knowledge model](docs/knowledge.md) · [Testing contract](docs/testing.md) · [Security & privacy](docs/security.md) · [Integrations](docs/integrations.md) · [Claude](docs/claude.md) · [Routing](docs/routing.md) · [Portability](docs/portability.md) · [Benchmarking](docs/benchmarking.md) · [Troubleshooting](docs/troubleshooting.md) · [Contributing](docs/contributing.md)
257
+ - [Getting Started](docs/getting-started.md)
258
+ - [Architecture & Design](docs/architecture.md)
259
+ - [Model Context Protocol (MCP)](docs/mcp.md)
260
+ - [Coding Agent Integrations](docs/agents.md)
261
+ - [Knowledge & Context Model](docs/knowledge.md)
262
+ - [Testing & Verification Contract](docs/testing.md)
263
+ - [Security & Threat Model](docs/security.md)
264
+ - [Integrations (Graphify, Skills, Ponytail)](docs/integrations.md)
265
+ - [Claude Code Guide](docs/claude.md)
266
+ - [Task Routing & Roles](docs/routing.md)
267
+ - [Portability & Git](docs/portability.md)
268
+ - [Benchmarking & Evaluation](docs/benchmarking.md)
269
+ - [Troubleshooting Guide](docs/troubleshooting.md)
270
+ - [Contributing](docs/contributing.md)
271
+
272
+ ---
167
273
 
168
274
  ## License
169
275
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "devworkspace",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "Project-local AI engineering workspace: deterministic repository discovery, portable project knowledge, tasks, decisions and verification gates for AI coding agents.",
5
5
  "type": "module",
6
6
  "bin": {