workspai 0.58.0 → 0.59.0

package/README.md

@@ -18,6 +18,10 @@ npx workspai adopt .
 npx workspai workspace intelligence run --for-agent generic
 ```
 
+`generic` is the safe default when you do not yet know which agent will use the
+project: Workspai builds one portable context and prepares discovery adapters
+for every supported host, without duplicating the Model or Graph.
+
 A single run gives developers and tools the same operational picture:
 
 ```text
@@ -96,6 +100,34 @@ workspai --help
 
 `wspai` is an optional short alias for the same CLI.
 
+## Give your agent a goal—not an open-ended prompt
+
+Describe the outcome in plain language from the adopted project:
+
+```bash
+npx workspai goal "Raise test coverage to 85%" --for-agent generic
+# Or pursue feature, defect, refactor, performance, documentation, or
+# system-understanding outcomes in the same governed flow.
+npx workspai goal "Add retry with exponential backoff" --for-agent generic
+```
+
+Workspai turns it into a bounded, evidence-backed handoff:
+
+```text
+Intent → project scope → proof-backed context → governed plan → safe execution
+```
+
+The agent gets a focused objective, not permission to scan or change
+everything. Workspai keeps approval, verification, and rollback under CLI
+control. The command prepares governed work; it does not edit source or claim
+that the outcome is complete. Exact coverage, dependency-security, and release
+Goals have deterministic CLI verifiers; other outcomes retain CLI safety and
+rollback while the consumer performs an evidence-backed outcome review.
+
+![Workspai turns a plain-language objective into a governed Goal Pack](https://raw.githubusercontent.com/chistiq/workspai/main/packages/cli/docs/workspai-goal-readme-cli.gif)
+
+[Learn how Goal Packs work](docs/goal-packs.md)
+
 ## What happens after the first run
 
 Workspai saves reusable results under `.workspai/`:
@@ -109,6 +141,19 @@ Workspai saves reusable results under `.workspai/`:
 It also prepares `AGENTS.md` and supported agent/IDE surfaces. Developers, CI,
 IDEs, MCP clients, and AI agents can therefore read the same current evidence.
 
+An agent can prove that it entered through that evidence before scanning the
+repository:
+
+```bash
+npx workspai agent bootstrap --for-agent codex --strict --json
+```
+
+The portable receipt checks workspace membership, host discovery, artifact
+schemas and integrity, Model/Graph freshness, live inputs, and the active Goal
+handoff. A blocked receipt prevents complete architecture or verification
+claims; it never falls back silently to a broad source scan. [Learn about
+canonical-first agent entry](docs/agent-entry.md).
+
 A blocked result is useful evidence, not a crashed command. Workspai names what
 is missing or failing and keeps the generated reports available for inspection.
 
@@ -158,19 +203,21 @@ The deterministic model, graph, and checks do not require an AI API key.
 
 ## Everyday workflows
 
-| Goal | Command |
-| --- | --- |
-| Use guided setup | `npx workspai create` |
-| Link a project without moving it | `npx workspai adopt .` |
-| Turn an outcome into governed work | `npx workspai goal "Raise test coverage to 85%"` |
-| Copy or clone a project into a workspace | `npx workspai import <path-or-git-url> --workspace <path>` |
-| Check the current project | `npx workspai doctor project` |
-| Check the whole workspace | `npx workspai doctor workspace` |
-| Refresh Model and Graph | `npx workspai workspace model --write --json` |
-| Ask a focused architecture question | `npx workspai workspace graph search "authentication service" --limit 12 --json` |
-| Verify current evidence | `npx workspai workspace verify --strict --json` |
-| Inspect a governed repair before execution | `npx workspai workspace repair capabilities --json` |
-| Refresh agent and IDE context | `npx workspai workspace agent-sync --write --preset enterprise --json` |
+| Goal                                       | Command                                                                          |
+| ------------------------------------------ | -------------------------------------------------------------------------------- |
+| Use guided setup                           | `npx workspai create`                                                            |
+| Link a project without moving it           | `npx workspai adopt .`                                                           |
+| Turn an outcome into governed work         | `npx workspai goal "Raise test coverage to 85%"`                                 |
+| Ground an agent before source discovery    | `npx workspai agent bootstrap --for-agent codex --strict --json`                 |
+| Audit every agent entry adapter            | `npx workspai project agent-entry verify --for-agent all --strict --json`        |
+| Copy or clone a project into a workspace   | `npx workspai import <path-or-git-url> --workspace <path>`                       |
+| Check the current project                  | `npx workspai doctor project`                                                    |
+| Check the whole workspace                  | `npx workspai doctor workspace`                                                  |
+| Refresh Model and Graph                    | `npx workspai workspace model --write --json`                                    |
+| Ask a focused architecture question        | `npx workspai workspace graph search "authentication service" --limit 12 --json` |
+| Verify current evidence                    | `npx workspai workspace verify --strict --json`                                  |
+| Inspect a governed repair before execution | `npx workspai workspace repair capabilities --json`                              |
+| Refresh agent and IDE context              | `npx workspai workspace agent-sync --write --preset enterprise --json`           |
 
 For every command and flag, use the
 [Command Reference](docs/commands-reference.md).
@@ -205,28 +252,29 @@ modules; Workspai remains the workspace-level CLI.
 
 ## Documentation
 
-| Goal | Guide |
-| --- | --- |
-| Learn the main terms | [Glossary](docs/GLOSSARY.md) |
-| Create, adopt, import, or connect software | [Creating workspaces and projects](docs/creating-workspaces-and-projects.md) |
-| Query Graph and inspect proof | [Workspace Knowledge Graph](docs/workspace-knowledge-graph.md) |
-| Understand the exact decision loop | [Workspace Intelligence runner](docs/workspace-intelligence-runner.md) |
-| Plan, approve, execute, or roll back a repair | [Workspace Repair Engine](docs/workspace-repair-engine.md) |
-| Set a release, security, or coverage outcome | [Verified engineering goals](docs/workspace-intelligence-runner.md#verified-engineering-goals) |
-| Compile plain language into a governed plan | [Goal Packs](docs/goal-packs.md) |
-| Integrate CI | [CI workflows](docs/ci-workflows.md) |
-| Find generated files and schemas | [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md) |
-| Browse all documentation | [Documentation index](docs/README.md) |
+| Goal                                          | Guide                                                                                          |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Learn the main terms                          | [Glossary](docs/GLOSSARY.md)                                                                   |
+| Create, adopt, import, or connect software    | [Creating workspaces and projects](docs/creating-workspaces-and-projects.md)                   |
+| Query Graph and inspect proof                 | [Workspace Knowledge Graph](docs/workspace-knowledge-graph.md)                                 |
+| Understand the exact decision loop            | [Workspace Intelligence runner](docs/workspace-intelligence-runner.md)                         |
+| Plan, approve, execute, or roll back a repair | [Workspace Repair Engine](docs/workspace-repair-engine.md)                                     |
+| Set a release, security, or coverage outcome  | [Verified engineering goals](docs/workspace-intelligence-runner.md#verified-engineering-goals) |
+| Compile plain language into a governed plan   | [Goal Packs](docs/goal-packs.md)                                                               |
+| Ground an agent in canonical project evidence | [Canonical-first agent entry](docs/agent-entry.md)                                             |
+| Integrate CI                                  | [CI workflows](docs/ci-workflows.md)                                                           |
+| Find generated files and schemas              | [Artifact Catalog](docs/contracts/ARTIFACT_CATALOG.md)                                         |
+| Browse all documentation                      | [Documentation index](docs/README.md)                                                          |
 
 ## Troubleshooting
 
-| Problem | Next step |
-| --- | --- |
-| The workspace is not detected | Run from the project/workspace or inspect `npx workspai project workspace status --json` |
-| A check reports stale evidence | Re-run the complete Workspace Intelligence command |
-| A runtime is missing | Install only the runtime required by that project |
-| An agent cannot find current context | Run `npx workspai workspace agent-sync --write --refresh-context --json` |
-| You need a specific flag | Open the [Command Reference](docs/commands-reference.md) |
+| Problem                              | Next step                                                                                |
+| ------------------------------------ | ---------------------------------------------------------------------------------------- |
+| The workspace is not detected        | Run from the project/workspace or inspect `npx workspai project workspace status --json` |
+| A check reports stale evidence       | Re-run the complete Workspace Intelligence command                                       |
+| A runtime is missing                 | Install only the runtime required by that project                                        |
+| An agent cannot find current context | Run `npx workspai workspace agent-sync --write --refresh-context --json`                 |
+| You need a specific flag             | Open the [Command Reference](docs/commands-reference.md)                                 |
 
 ## Contributing
 

package/contracts/agent-customization-pack.v1.json

@@ -32,7 +32,13 @@
         "vscode",
         "copilot",
         "cursor",
-        "claude"
+        "claude",
+        "gemini",
+        "qwen",
+        "kimi",
+        "grok",
+        "windsurf",
+        "amazon-q"
       ]
     },
     "vscode": {
@@ -78,8 +84,47 @@
         "portable"
       ]
     },
+    "gemini": {
+      "meaning": "Generate Gemini CLI grounding through GEMINI.md and canonical AGENTS.md.",
+      "outputFamilies": [
+        "adapter",
+        "portable"
+      ]
+    },
+    "qwen": {
+      "meaning": "Generate Qwen Code grounding through QWEN.md and canonical AGENTS.md.",
+      "outputFamilies": [
+        "adapter",
+        "portable"
+      ]
+    },
+    "kimi": {
+      "meaning": "Use AGENTS.md and the report index as the Kimi Code grounding layer.",
+      "outputFamilies": [
+        "portable"
+      ]
+    },
+    "grok": {
+      "meaning": "Use AGENTS.md and the report index as the xAI Grok grounding layer.",
+      "outputFamilies": [
+        "portable"
+      ]
+    },
+    "windsurf": {
+      "meaning": "Use AGENTS.md and the report index as the Windsurf grounding layer.",
+      "outputFamilies": [
+        "portable"
+      ]
+    },
+    "amazon-q": {
+      "meaning": "Generate an Amazon Q project rule that routes agents to canonical evidence.",
+      "outputFamilies": [
+        "rules",
+        "portable"
+      ]
+    },
     "orca": {
-      "meaning": "Use AGENTS.md and the report index as the Orca/Grok grounding layer.",
+      "meaning": "Legacy compatibility alias for AGENTS.md consumers; prefer the grok target.",
       "outputFamilies": [
         "portable"
       ]
@@ -238,12 +283,15 @@
     "l2PrefixedMirrorRoots": [
       ".github/",
       ".cursor/",
-      ".claude/"
+      ".claude/",
+      ".amazonq/"
     ],
     "l3SharedIndustryFiles": [
       "AGENTS.md",
       ".github/copilot-instructions.md",
-      "CLAUDE.md"
+      "CLAUDE.md",
+      "GEMINI.md",
+      "QWEN.md"
     ]
   }
 }

package/contracts/cli-runtime-command-inventory.v1.snapshot.json

@@ -45,6 +45,54 @@
         }
       ]
     },
+    {
+      "path": [
+        "agent"
+      ],
+      "command": "agent",
+      "parent": null,
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Bootstrap coding agents from canonical Workspai project evidence",
+      "hidden": false,
+      "arguments": [],
+      "options": []
+    },
+    {
+      "path": [
+        "agent",
+        "bootstrap"
+      ],
+      "command": "bootstrap",
+      "parent": "agent",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Issue a portable canonical-first grounding receipt for the current project",
+      "hidden": false,
+      "arguments": [],
+      "options": [
+        {
+          "flags": "--project <path>",
+          "attributeName": "project"
+        },
+        {
+          "flags": "--for-agent <agent>",
+          "attributeName": "forAgent"
+        },
+        {
+          "flags": "--no-live-inputs",
+          "attributeName": "liveInputs"
+        },
+        {
+          "flags": "--strict",
+          "attributeName": "strict"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        }
+      ]
+    },
     {
       "path": [
         "ai"
@@ -865,6 +913,47 @@
       "arguments": [],
       "options": []
     },
+    {
+      "path": [
+        "project",
+        "agent-entry"
+      ],
+      "command": "agent-entry",
+      "parent": "project",
+      "registrationKind": "commander",
+      "aliases": [],
+      "description": "Verify canonical-first project entry coverage for supported agent hosts",
+      "hidden": false,
+      "arguments": [
+        {
+          "name": "action",
+          "required": false,
+          "variadic": false
+        }
+      ],
+      "options": [
+        {
+          "flags": "--project <path>",
+          "attributeName": "project"
+        },
+        {
+          "flags": "--for-agent <agent>",
+          "attributeName": "forAgent"
+        },
+        {
+          "flags": "--no-live-inputs",
+          "attributeName": "liveInputs"
+        },
+        {
+          "flags": "--strict",
+          "attributeName": "strict"
+        },
+        {
+          "flags": "--json",
+          "attributeName": "json"
+        }
+      ]
+    },
     {
       "path": [
         "project",
@@ -1597,6 +1686,7 @@
   ],
   "topLevelCommands": [
     "adopt",
+    "agent",
     "ai",
     "analyze",
     "autopilot",

package/contracts/extension-cli-compatibility.v1.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "rapidkit-extension-cli-compatibility.v1",
   "cli": "workspai",
-  "minimumVerifiedCliVersion": "0.56.0",
+  "minimumVerifiedCliVersion": "0.58.0",
   "publishedContractSchemas": {
     "workspaceContract": 1,
     "runtimeCommandSurface": "rapidkit-runtime-command-surface-v1",
@@ -18,6 +18,8 @@
     "projectWorkspaceLink": "project-workspace-link.v1",
     "projectWorkspaceResolution": "project-workspace-resolution.v1",
     "projectContextAgent": "project-context-agent.v1",
+    "projectAgentEntry": "workspai.agent-entry.v1",
+    "agentBootstrapReceipt": "workspai.agent-bootstrap-receipt.v1",
     "doctorProjectEvidence": "doctor-project-evidence-v1",
     "doctorWorkspaceEvidence": "doctor-workspace-evidence-v1",
     "doctorGraphDiagnosis": "doctor-graph-diagnosis.v1",

package/contracts/project-workspace-resolution.v1.json

@@ -12,7 +12,8 @@
     "source",
     "recovered",
     "linkPath",
-    "nextCommand"
+    "nextCommand",
+    "pathPolicy"
   ],
   "properties": {
     "schemaVersion": { "const": "project-workspace-resolution.v1" },
@@ -22,7 +23,19 @@
     "source": { "enum": ["explicit", "parent", "local-link", "registry"] },
     "recovered": { "type": "boolean" },
     "linkPath": { "type": "string", "minLength": 1 },
-    "nextCommand": { "type": "string", "minLength": 1 }
+    "nextCommand": { "type": "string", "minLength": 1 },
+    "pathPolicy": {
+      "type": "object",
+      "required": ["classification", "portable", "persistence", "disclosure", "purpose"],
+      "properties": {
+        "classification": { "const": "machine-local" },
+        "portable": { "const": false },
+        "persistence": { "const": "forbidden" },
+        "disclosure": { "const": "forbidden" },
+        "purpose": { "const": "runtime-workspace-resolution" }
+      },
+      "additionalProperties": false
+    }
   },
   "additionalProperties": false
 }

package/contracts/published-contract-catalog.v1.json

@@ -76,6 +76,16 @@
       "contractPath": "contracts/workspace-intelligence/project-context-agent.v1.json",
       "publication": "json-schema"
     },
+    "projectAgentEntry": {
+      "schemaVersion": "workspai.agent-entry.v1",
+      "contractPath": "contracts/workspace-intelligence/project-agent-entry.v1.json",
+      "publication": "json-schema"
+    },
+    "agentBootstrapReceipt": {
+      "schemaVersion": "workspai.agent-bootstrap-receipt.v1",
+      "contractPath": "contracts/workspace-intelligence/agent-bootstrap-receipt.v1.json",
+      "publication": "json-schema"
+    },
     "doctorProjectEvidence": {
       "schemaVersion": "doctor-project-evidence-v1",
       "contractPath": "contracts/doctor-project-evidence.v1.json",

package/contracts/runtime-command-surface.v1.json

@@ -49,6 +49,7 @@
     "import",
     "adopt",
     "goal",
+    "agent",
     "snapshot",
     "bootstrap",
     "setup",
@@ -80,6 +81,10 @@
       "ai",
       "update-embeddings"
     ],
+    [
+      "agent",
+      "bootstrap"
+    ],
     [
       "config",
       "ai"
@@ -129,6 +134,10 @@
       "project",
       "commands"
     ],
+    [
+      "project",
+      "agent-entry"
+    ],
     [
       "project",
       "coverage"
@@ -185,6 +194,21 @@
         "adopt"
       ]
     },
+    {
+      "invocation": "agent",
+      "summary": "Resolve portable project entry contracts and issue canonical-first grounding receipts for coding agents.",
+      "canonicalArgv": [
+        "agent"
+      ]
+    },
+    {
+      "invocation": "agent bootstrap",
+      "summary": "Validate host discovery, workspace membership, evidence freshness, live inputs, and active Goal bindings before broad source discovery.",
+      "canonicalArgv": [
+        "agent",
+        "bootstrap"
+      ]
+    },
     {
       "invocation": "ai",
       "summary": "Manage AI configuration, recommendations, and embedding operations for the active workspace.",
@@ -639,6 +663,14 @@
         "project"
       ]
     },
+    {
+      "invocation": "project agent-entry",
+      "summary": "Verify portable entry adapters and canonical evidence bindings for one or every supported agent host.",
+      "canonicalArgv": [
+        "project",
+        "agent-entry"
+      ]
+    },
     {
       "invocation": "project archive",
       "summary": "Move a project into governed archive storage while preserving registry metadata and recovery evidence.",
@@ -1869,6 +1901,28 @@
         ]
       ]
     },
+    {
+      "artifactPath": ".workspai/agent-entry.v1.json",
+      "schemaVersion": "workspai.agent-entry.v1",
+      "contractPath": "contracts/workspace-intelligence/project-agent-entry.v1.json",
+      "producerCommands": [
+        [
+          "adopt"
+        ],
+        [
+          "import"
+        ],
+        [
+          "workspace",
+          "sync"
+        ],
+        [
+          "workspace",
+          "agent-sync",
+          "--write"
+        ]
+      ]
+    },
     {
       "artifactPath": ".workspai/workspace.contract.json",
       "schemaVersion": 1,