minutework 0.1.29 → 0.1.31
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.
- package/EXTERNAL_ALPHA.md +33 -33
- package/README.md +35 -33
- package/assets/claude-local/CLAUDE.md.template +12 -12
- package/assets/claude-local/skills/README.md +1 -1
- package/assets/claude-local/skills/app-pack-authoring/SKILL.md +3 -3
- package/assets/claude-local/skills/capability-gap-reporting/SKILL.md +3 -3
- package/assets/claude-local/skills/generated-workspace-architecture/SKILL.md +4 -3
- package/assets/claude-local/skills/layering-and-import-modes/SKILL.md +2 -2
- package/assets/claude-local/skills/openclaw-skill-importer/SKILL.md +2 -2
- package/assets/claude-local/skills/project-overview-and-strategy/SKILL.md +8 -8
- package/assets/claude-local/skills/published-web-and-mw-core-site/SKILL.md +2 -2
- package/assets/claude-local/skills/runtime-capability-inventory/SKILL.md +6 -1
- package/assets/claude-local/skills/standalone-mobile-client/SKILL.md +8 -1
- package/assets/claude-local/skills/vuilder-discovery-output-contract/SKILL.md +6 -6
- package/assets/claude-local/skills/workspace-guidance-refresh/SKILL.md +4 -4
- package/assets/templates/fastapi-sidecar/pyproject.toml +1 -1
- package/assets/templates/fastapi-sidecar/src/fastapi_sidecar/main.py +1 -1
- package/assets/templates/mobile-app/.env.example +7 -5
- package/assets/templates/mobile-app/AGENTS.md +8 -3
- package/assets/templates/mobile-app/README.md +22 -16
- package/assets/templates/mobile-app/app/(app)/_layout.tsx +2 -2
- package/assets/templates/mobile-app/app/(app)/index.tsx +2 -2
- package/assets/templates/mobile-app/app/(auth)/login.tsx +3 -3
- package/assets/templates/mobile-app/app/_layout.tsx +1 -1
- package/assets/templates/mobile-app/app.json +0 -3
- package/assets/templates/mobile-app/babel.config.js +1 -1
- package/assets/templates/mobile-app/eas.json +1 -1
- package/assets/templates/mobile-app/expo-env.d.ts +1 -1
- package/assets/templates/mobile-app/metro.config.js +12 -2
- package/assets/templates/mobile-app/package.json +19 -15
- package/assets/templates/mobile-app/src/mw/client.ts +3 -3
- package/assets/templates/mobile-app/src/mw/contracts.ts +2 -2
- package/assets/templates/mobile-app/src/mw/endpoints.ts +2 -2
- package/assets/templates/mobile-app/src/mw/env.ts +13 -5
- package/assets/templates/mobile-app/src/mw/session.ts +1 -1
- package/assets/templates/mobile-app/template.json +1 -1
- package/assets/templates/mobile-app/tools/template/validate-template.mjs +2 -2
- package/assets/templates/mobile-app/tsconfig.json +1 -1
- package/assets/templates/next-tenant-app/.env.example +1 -1
- package/assets/templates/next-tenant-app/README.md +3 -3
- package/assets/templates/next-tenant-app/src/app/app/examples/runtime-commands/page.test.ts +2 -2
- package/assets/templates/next-tenant-app/src/app/app/page.test.ts +1 -1
- package/assets/templates/next-tenant-app/src/app/app/page.tsx +1 -1
- package/assets/templates/next-tenant-app/src/app/blog/[slug]/page.test.ts +1 -1
- package/assets/templates/next-tenant-app/src/app/docs/[...slug]/page.test.ts +1 -1
- package/assets/templates/next-tenant-app/src/app/login/page.test.ts +1 -1
- package/assets/templates/next-tenant-app/src/app/login/page.tsx +1 -1
- package/assets/templates/next-tenant-app/src/app/page.test.ts +2 -2
- package/assets/templates/next-tenant-app/src/app/pricing/page.test.ts +2 -2
- package/assets/templates/next-tenant-app/src/lib/content/__fixtures__/public-site-snapshot.ts +14 -14
- package/assets/templates/next-tenant-app/src/lib/content/adapter.server.test.ts +3 -3
- package/assets/templates/next-tenant-app/src/lib/content/adapter.server.ts +1 -1
- package/assets/templates/next-tenant-app/src/lib/content/empty-state.ts +3 -3
- package/assets/templates/next-tenant-app/src/lib/platform/env.server.test.ts +2 -2
- package/assets/templates/next-tenant-app/src/lib/platform/env.server.ts +1 -1
- package/assets/templates/next-tenant-app/src/lib/public-site.test.ts +1 -1
- package/assets/templates/next-tenant-app/tools/template/with-public-site-fixture.mjs +2 -2
- package/bin/minutework.js +1 -1
- package/dist/agent.js +7 -7
- package/dist/agent.js.map +1 -1
- package/dist/auth.js +7 -7
- package/dist/auth.js.map +1 -1
- package/dist/compile.js +5 -5
- package/dist/config.js +6 -6
- package/dist/config.js.map +1 -1
- package/dist/deploy.js +7 -7
- package/dist/deploy.js.map +1 -1
- package/dist/developer-client.js +2 -2
- package/dist/developer-client.js.map +1 -1
- package/dist/index.js +31 -28
- package/dist/index.js.map +1 -1
- package/dist/init.js +24 -27
- package/dist/init.js.map +1 -1
- package/dist/launcher.js +1 -1
- package/dist/launcher.js.map +1 -1
- package/dist/managed-engine.js +6 -6
- package/dist/managed-engine.js.map +1 -1
- package/dist/orchestrator-context.js +1 -1
- package/dist/orchestrator-context.js.map +1 -1
- package/dist/orchestrator.js +15 -15
- package/dist/orchestrator.js.map +1 -1
- package/dist/paths.js +1 -1
- package/dist/paths.js.map +1 -1
- package/dist/publish.js +3 -3
- package/dist/publish.js.map +1 -1
- package/dist/reporting.js +8 -8
- package/dist/reporting.js.map +1 -1
- package/dist/sandbox.js +5 -5
- package/dist/sandbox.js.map +1 -1
- package/dist/state.js +1 -1
- package/dist/state.js.map +1 -1
- package/dist/tokens.js +9 -9
- package/dist/tokens.js.map +1 -1
- package/dist/workspace-assets.js +6 -6
- package/dist/workspace-assets.js.map +1 -1
- package/dist/workspace.js +3 -3
- package/dist/workspace.js.map +1 -1
- package/package.json +4 -3
- package/vendor/workspace-mcp/context.d.ts +6 -6
- package/vendor/workspace-mcp/context.js +56 -56
- package/vendor/workspace-mcp/context.js.map +1 -1
package/EXTERNAL_ALPHA.md
CHANGED
|
@@ -1,35 +1,35 @@
|
|
|
1
|
-
#
|
|
1
|
+
# PandaWork CLI External Alpha
|
|
2
2
|
|
|
3
|
-
This document is the operator-facing onboarding contract for the first external
|
|
3
|
+
This document is the operator-facing onboarding contract for the first external PandaWork CLI alpha.
|
|
4
4
|
|
|
5
5
|
## Supported paths
|
|
6
6
|
|
|
7
7
|
Every supported external path starts with the same workspace/bootstrap flow:
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
npx
|
|
10
|
+
npx pandawork init my-site --starter tenant-app
|
|
11
11
|
cd my-site
|
|
12
|
-
npx
|
|
13
|
-
npx
|
|
12
|
+
npx pandawork login
|
|
13
|
+
npx pandawork link
|
|
14
14
|
```
|
|
15
15
|
|
|
16
16
|
From there, the current external alpha supports two post-link lanes.
|
|
17
17
|
|
|
18
18
|
The shipped `tenant-app` starter is the combined web surface: public routes at
|
|
19
|
-
the root, a private `/app` workspace, and a
|
|
19
|
+
the root, a private `/app` workspace, and a PandaWork-managed public-content
|
|
20
20
|
path over the runtime-baseline `mw.core.site` contract.
|
|
21
21
|
|
|
22
22
|
### Developer-local broker lane
|
|
23
23
|
|
|
24
|
-
Use `
|
|
24
|
+
Use `pandawork session` when you want PandaWork to assemble the workspace
|
|
25
25
|
snapshot, choose a local workflow mode, and optionally launch the first shipped
|
|
26
26
|
local coding engine.
|
|
27
27
|
|
|
28
28
|
```bash
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
29
|
+
pandawork session start --mode human
|
|
30
|
+
pandawork session start --mode ai --engine claude
|
|
31
|
+
pandawork session status
|
|
32
|
+
pandawork session resume
|
|
33
33
|
```
|
|
34
34
|
|
|
35
35
|
- `start` stores or updates the workspace preference, writes a bounded context
|
|
@@ -41,10 +41,10 @@ minutework session resume
|
|
|
41
41
|
- `human` and `ai` are alternative start modes, not a required sequence.
|
|
42
42
|
- Claude is the only supported local coding engine today.
|
|
43
43
|
- AI mode now auto-installs and auto-updates managed Claude Code under the
|
|
44
|
-
machine-local
|
|
44
|
+
machine-local PandaWork CLI state root and prefers that managed binary over
|
|
45
45
|
any `claude` already on `PATH`.
|
|
46
|
-
- Claude authentication still happens outside
|
|
47
|
-
login or approval, complete that in Claude itself and rerun the
|
|
46
|
+
- Claude authentication still happens outside PandaWork. If Claude needs local
|
|
47
|
+
login or approval, complete that in Claude itself and rerun the PandaWork
|
|
48
48
|
broker command.
|
|
49
49
|
|
|
50
50
|
The broker state model is intentionally split:
|
|
@@ -52,7 +52,7 @@ The broker state model is intentionally split:
|
|
|
52
52
|
- repo-local pointer and lock state under `.minutework/` tracks the current
|
|
53
53
|
workspace session
|
|
54
54
|
- machine-local preferences, per-session context packs, transcripts, and
|
|
55
|
-
session history stay under the
|
|
55
|
+
session history stay under the PandaWork CLI state root
|
|
56
56
|
|
|
57
57
|
The broker fails closed when a live session is already active, the selected
|
|
58
58
|
engine is missing, a prior running record has gone stale, or the launch is
|
|
@@ -74,7 +74,7 @@ trusted projects); `mcp/claude-desktop.sample.json` is included for Claude
|
|
|
74
74
|
Desktop.
|
|
75
75
|
|
|
76
76
|
Generated guidance and MCP wiring can be reconciled later with
|
|
77
|
-
`
|
|
77
|
+
`pandawork workspace sync-assets`.
|
|
78
78
|
|
|
79
79
|
Runtime-only Claude hooks remain excluded from the generated workspace export.
|
|
80
80
|
|
|
@@ -84,28 +84,28 @@ Use the existing local preview/test loop and hosted preview deploy lane when
|
|
|
84
84
|
you want to run the generated app locally or submit a hosted preview:
|
|
85
85
|
|
|
86
86
|
```bash
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
87
|
+
pandawork dev
|
|
88
|
+
pandawork test
|
|
89
|
+
pandawork deploy --preview
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
-
Combined **tenant-app + sidecar** workspaces keep sidecar setup explicit. Root `pnpm install` stays Node-only and does not run `poetry install` for you. If you need the sidecar, run `pnpm run install:sidecar` from the workspace root or `cd sidecar && poetry install` yourself before `
|
|
92
|
+
Combined **tenant-app + sidecar** workspaces keep sidecar setup explicit. Root `pnpm install` stays Node-only and does not run `poetry install` for you. If you need the sidecar, run `pnpm run install:sidecar` from the workspace root or `cd sidecar && poetry install` yourself before `pandawork dev` or `pandawork test`.
|
|
93
93
|
|
|
94
94
|
For direct third-party web hosts such as Vercel, deploy `tenant-app` only. In Vercel, point the project Root Directory at `tenant-app`; the optional sidecar remains a separate Poetry-managed surface.
|
|
95
95
|
|
|
96
96
|
For native mobile clients, use the `mobile` starter. It is a standalone Expo /
|
|
97
97
|
React Native client that authenticates directly against the platform with the
|
|
98
98
|
native session-token flow; it is distributed through EAS/App Store/Play Store
|
|
99
|
-
instead of `
|
|
99
|
+
instead of `pandawork deploy`.
|
|
100
100
|
|
|
101
101
|
Anything outside these lanes remains deferred, including `--live`,
|
|
102
102
|
runtime-backed deploy targets, and additional local coding engines.
|
|
103
103
|
|
|
104
|
-
If you run `
|
|
104
|
+
If you run `pandawork init` **without** `--starter` in an interactive terminal, the CLI prompts for tenant-app, sidecar, mobile, common combinations, or base-only. In CI or scripts, use `--starter` or set `MW_CLI_NONINTERACTIVE=1` to skip the prompt (base-only scaffold).
|
|
105
105
|
|
|
106
106
|
## What `link` does
|
|
107
107
|
|
|
108
|
-
`
|
|
108
|
+
`pandawork link` is no longer tenant-only. It now:
|
|
109
109
|
|
|
110
110
|
1. Resolves the active auth profile and workspace platform.
|
|
111
111
|
2. Resolves or creates the tenant-scoped `PublishedWebProperty`.
|
|
@@ -133,7 +133,7 @@ If the workspace cannot compile hosted preview release metadata for the linked p
|
|
|
133
133
|
|
|
134
134
|
## What `deploy --preview` does
|
|
135
135
|
|
|
136
|
-
`
|
|
136
|
+
`pandawork deploy --preview` is preview-only and guarded:
|
|
137
137
|
|
|
138
138
|
1. Loads the active auth profile and linked workspace property.
|
|
139
139
|
2. Re-runs validate and compile.
|
|
@@ -153,12 +153,12 @@ The CLI does not fabricate success. If the backend cannot materialize a hosted p
|
|
|
153
153
|
|
|
154
154
|
## Failure semantics
|
|
155
155
|
|
|
156
|
-
- Missing auth: run `
|
|
157
|
-
- Missing binding: run `
|
|
158
|
-
- Missing stored broker preference before resume: run `
|
|
159
|
-
- Missing Claude binary or local Claude auth for AI mode: let
|
|
160
|
-
- Live or stale local broker session state: inspect `
|
|
161
|
-
- Missing property-scoped release metadata: fix `tenant-app/.env.example` and re-run `
|
|
156
|
+
- Missing auth: run `pandawork login`
|
|
157
|
+
- Missing binding: run `pandawork link`
|
|
158
|
+
- Missing stored broker preference before resume: run `pandawork session start --mode <human|ai>`
|
|
159
|
+
- Missing Claude binary or local Claude auth for AI mode: let PandaWork retry the managed install when network access is available, or complete Claude authentication locally, then rerun `pandawork session start --mode ai --engine claude`
|
|
160
|
+
- Live or stale local broker session state: inspect `pandawork session status`, let the live process exit, or rerun `pandawork session resume`
|
|
161
|
+
- Missing property-scoped release metadata: fix `tenant-app/.env.example` and re-run `pandawork compile`
|
|
162
162
|
- Unsupported release class: external alpha only supports hosted `ssr_container`
|
|
163
163
|
- Missing provider/receipt substrate: deploy returns a typed failure receipt
|
|
164
164
|
- Failed preview deploy with an existing preview target: the platform reports `rolled_back` with `previous_preview_preserved`
|
|
@@ -166,9 +166,9 @@ The CLI does not fabricate success. If the backend cannot materialize a hosted p
|
|
|
166
166
|
## CLI bug reports
|
|
167
167
|
|
|
168
168
|
- The CLI automatically submits a sanitized bug report for failed commands unless `MW_CLI_BUG_REPORTS=never` is set (machine-readable `--json` verbs suppress this automatically).
|
|
169
|
-
- Automatic reports keep a local JSON bundle under the
|
|
170
|
-
- `
|
|
171
|
-
- `
|
|
169
|
+
- Automatic reports keep a local JSON bundle under the PandaWork CLI state root for retry and support follow-up.
|
|
170
|
+
- `pandawork report-bug --note "..."` sends a manual report for UX issues or suspicious behavior that did not crash.
|
|
171
|
+
- `pandawork report-bug --last --note "..."` resends the last saved bundle with extra context.
|
|
172
172
|
- Support should always ask for the printed `report_id` before requesting extra screenshots or logs.
|
|
173
173
|
|
|
174
174
|
## Release notes for operators
|
package/README.md
CHANGED
|
@@ -1,29 +1,31 @@
|
|
|
1
|
-
#
|
|
1
|
+
# PandaWork CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
PandaWork CLI for initializing a workspace, authenticating against a PandaWork platform, linking a repo to a tenant-scoped public-site property, launching developer-local session broker flows, running local preview/test loops, submitting hosted preview deploys, and publishing app packs to the marketplace through the publication-review gate.
|
|
4
|
+
|
|
5
|
+
The npm package is still published as `minutework` for compatibility. Use `pandawork` for new commands; the existing `minutework` command remains supported.
|
|
4
6
|
|
|
5
7
|
## External alpha scope
|
|
6
8
|
|
|
7
9
|
The current external alpha is intentionally narrow:
|
|
8
10
|
|
|
9
11
|
- Starters: `tenant-app` (the deployable web surface), `sidecar` (local/internal runtime surface), and `mobile` (init-only native client)
|
|
10
|
-
- Developer-local broker surface: `
|
|
12
|
+
- Developer-local broker surface: `pandawork session start|resume|status`
|
|
11
13
|
- Hosted release class: `ssr_container`
|
|
12
|
-
- Deploy surface: `
|
|
14
|
+
- Deploy surface: `pandawork deploy --preview`
|
|
13
15
|
- Deferred: `--live`, additional local coding engines, sidecar/runtime-backed deploys, and the commercial marketplace listing/pricing layer
|
|
14
|
-
- Marketplace publish: `
|
|
16
|
+
- Marketplace publish: `pandawork publish` submits the compiled, digest-bound app pack through the platform publication-review + attestation gate and publishes it to the public marketplace catalog **only** on an approved (or approved-with-warnings) attestation; a rejected attestation prints the review findings and exits 1 without publishing
|
|
15
17
|
|
|
16
18
|
The shipped `tenant-app` starter is the combined web surface: public routes at
|
|
17
19
|
the root plus a private `/app` workspace. Public-site content follows the
|
|
18
|
-
|
|
20
|
+
PandaWork-managed `mw.core.site` baseline and published-snapshot flow.
|
|
19
21
|
|
|
20
22
|
The CLI fails closed when the backend cannot provide typed release metadata, deploy status, receipts, activation state, or rollback state. It does not claim a successful deploy when the provider substrate is unavailable.
|
|
21
23
|
|
|
22
24
|
## Install
|
|
23
25
|
|
|
24
26
|
```bash
|
|
25
|
-
npx
|
|
26
|
-
npx
|
|
27
|
+
npx pandawork --help
|
|
28
|
+
npx pandawork --version
|
|
27
29
|
```
|
|
28
30
|
|
|
29
31
|
For repeat use in a local environment:
|
|
@@ -39,10 +41,10 @@ The package currently ships on a `0.x` alpha channel. Publish from this repo wit
|
|
|
39
41
|
Start with the shared setup:
|
|
40
42
|
|
|
41
43
|
```bash
|
|
42
|
-
npx
|
|
44
|
+
npx pandawork init my-site --starter tenant-app
|
|
43
45
|
cd my-site
|
|
44
|
-
npx
|
|
45
|
-
npx
|
|
46
|
+
npx pandawork login
|
|
47
|
+
npx pandawork link
|
|
46
48
|
```
|
|
47
49
|
|
|
48
50
|
After `link`, the current alpha has two supported lanes (both `tenant-app`).
|
|
@@ -50,7 +52,7 @@ After `link`, the current alpha has two supported lanes (both `tenant-app`).
|
|
|
50
52
|
For a native mobile client, scaffold the **`mobile`** starter instead:
|
|
51
53
|
|
|
52
54
|
```bash
|
|
53
|
-
npx
|
|
55
|
+
npx pandawork init my-app --starter mobile
|
|
54
56
|
```
|
|
55
57
|
|
|
56
58
|
It is **init-only** and bring-your-own-UI: a minimal Expo (React Native) client
|
|
@@ -58,34 +60,34 @@ that authenticates **directly** against the platform with a native device-flow
|
|
|
58
60
|
session token (PKCE authorize -> exchange -> bearer + refresh in the device
|
|
59
61
|
keychain), not the `tenant-app` BFF cookie path. There is no `link`/`deploy`
|
|
60
62
|
lane for it — distribution is your own EAS pipeline (`eas build`/`eas submit`,
|
|
61
|
-
EAS Update), not `
|
|
63
|
+
EAS Update), not `pandawork deploy`.
|
|
62
64
|
|
|
63
65
|
### Developer-local broker lane
|
|
64
66
|
|
|
65
|
-
Use this lane when you want
|
|
67
|
+
Use this lane when you want PandaWork to assemble a bounded workspace context,
|
|
66
68
|
persist broker state locally, and either prepare a human-mode session or launch
|
|
67
69
|
the first supported local coding engine.
|
|
68
70
|
|
|
69
71
|
```bash
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
72
|
+
pandawork session start --mode human
|
|
73
|
+
pandawork session start --mode ai --engine claude
|
|
74
|
+
pandawork session status
|
|
75
|
+
pandawork session resume
|
|
74
76
|
```
|
|
75
77
|
|
|
76
78
|
- `human` and `ai` are alternative start modes, not a required sequence.
|
|
77
79
|
- Claude is the only supported local coding engine today.
|
|
78
80
|
- AI mode launches Claude with explicit workspace MCP bootstrap plus a bounded
|
|
79
|
-
|
|
80
|
-
-
|
|
81
|
+
PandaWork context pack instead of relying on implicit shell state.
|
|
82
|
+
- PandaWork now installs and updates managed Claude Code automatically under
|
|
81
83
|
the machine-local CLI state root when AI mode needs it, and prefers that
|
|
82
84
|
managed Claude binary over any `claude` already on `PATH`.
|
|
83
|
-
- Claude authentication still happens outside
|
|
85
|
+
- Claude authentication still happens outside PandaWork. If Claude needs local
|
|
84
86
|
login or account approval, complete that in Claude itself and rerun the
|
|
85
|
-
|
|
87
|
+
PandaWork session command.
|
|
86
88
|
- Current-session coordination stays repo-local under `.minutework/`, while
|
|
87
89
|
preferences, per-session context packs, transcripts, and session history stay
|
|
88
|
-
machine-local under the
|
|
90
|
+
machine-local under the PandaWork CLI state root.
|
|
89
91
|
- The broker fails closed on live overlap, missing engine binaries, stale
|
|
90
92
|
session records, interrupts, and launch failures instead of allowing
|
|
91
93
|
overlapping phantom sessions.
|
|
@@ -102,7 +104,7 @@ minutework session resume
|
|
|
102
104
|
trusted projects); `mcp/claude-desktop.sample.json` is included for Claude
|
|
103
105
|
Desktop.
|
|
104
106
|
- Managed guidance and MCP wiring can be refreshed later with
|
|
105
|
-
`
|
|
107
|
+
`pandawork workspace sync-assets`.
|
|
106
108
|
- Runtime-only Claude hooks are not exported into the generated workspace.
|
|
107
109
|
|
|
108
110
|
### Local preview and deploy lane
|
|
@@ -111,12 +113,12 @@ Use this lane when you want the workspace-local preview/test loop or a hosted
|
|
|
111
113
|
preview deploy:
|
|
112
114
|
|
|
113
115
|
```bash
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
116
|
+
pandawork dev
|
|
117
|
+
pandawork test
|
|
118
|
+
pandawork deploy --preview
|
|
117
119
|
```
|
|
118
120
|
|
|
119
|
-
Combined **tenant-app + sidecar** workspaces keep sidecar setup explicit. Root `pnpm install` stays Node-only and does not run `poetry install` for you. If you need the sidecar, run `pnpm run install:sidecar` from the workspace root or `cd sidecar && poetry install` yourself before `
|
|
121
|
+
Combined **tenant-app + sidecar** workspaces keep sidecar setup explicit. Root `pnpm install` stays Node-only and does not run `poetry install` for you. If you need the sidecar, run `pnpm run install:sidecar` from the workspace root or `cd sidecar && poetry install` yourself before `pandawork dev` or `pandawork test`. Sidecar-only scaffolds have no root `package.json`; install Python deps once inside `sidecar/` before running local sidecar workflows.
|
|
120
122
|
|
|
121
123
|
For direct third-party web hosts such as Vercel, deploy `tenant-app` only. In Vercel, point the project Root Directory at `tenant-app`; the optional sidecar remains a separate Poetry-managed surface.
|
|
122
124
|
|
|
@@ -146,20 +148,20 @@ For direct third-party web hosts such as Vercel, deploy `tenant-app` only. In Ve
|
|
|
146
148
|
|
|
147
149
|
## Bug reporting
|
|
148
150
|
|
|
149
|
-
CLI failures automatically send a sanitized diagnostic report to the
|
|
151
|
+
CLI failures automatically send a sanitized diagnostic report to the PandaWork platform unless `MW_CLI_BUG_REPORTS=never` is set.
|
|
150
152
|
|
|
151
153
|
- Machine-readable verbs run with `--json` suppress automatic reporting; rely on the result envelope and exit code instead.
|
|
152
154
|
|
|
153
155
|
- Automatic reports never include raw `.env` contents, tokens, source files, or full local paths.
|
|
154
|
-
- The CLI keeps a local report bundle under the
|
|
155
|
-
- Use `
|
|
156
|
-
- Use `
|
|
156
|
+
- The CLI keeps a local report bundle under the PandaWork state root so you can retry or inspect what was sent.
|
|
157
|
+
- Use `pandawork report-bug --note "what happened"` for manual reports.
|
|
158
|
+
- Use `pandawork report-bug --last --note "extra context"` to resend the last saved bundle with more detail.
|
|
157
159
|
|
|
158
160
|
## Requirements
|
|
159
161
|
|
|
160
162
|
- Node.js 18 or newer
|
|
161
163
|
- [Poetry](https://python-poetry.org/) on `PATH` when your workspace includes the FastAPI sidecar and you plan to run it locally (then run `pnpm run install:sidecar` or `cd sidecar && poetry install`)
|
|
162
|
-
- A
|
|
164
|
+
- A PandaWork platform that exposes the developer CLI auth and public-site preview deploy endpoints
|
|
163
165
|
- An auth profile with interactive developer access, or a deploy token that includes `deploy.preview.request`
|
|
164
166
|
|
|
165
167
|
If the hosted preview provider is not configured, preview deploy returns a typed failure or rollback-preserved receipt instead of a fake success.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
#
|
|
1
|
+
# PandaWork Builder
|
|
2
2
|
|
|
3
|
-
Use this workspace to build or extend
|
|
3
|
+
Use this workspace to build or extend PandaWork app packs. `tenant-app`,
|
|
4
4
|
`sidecar`, and optional `mobile` are implementation surfaces; choose the
|
|
5
5
|
smallest surface that fits the request.
|
|
6
6
|
|
|
@@ -10,27 +10,27 @@ private authenticated workspace under `/app`.
|
|
|
10
10
|
`mobile` is the standalone Expo/React Native client starter. It talks directly
|
|
11
11
|
to the platform with native device-flow auth and bearer tokens; it is not a
|
|
12
12
|
`tenant-app` BFF cookie client and not a `sidecar`. It ships through the
|
|
13
|
-
developer's own EAS/App Store/Play Store pipeline, not `
|
|
13
|
+
developer's own EAS/App Store/Play Store pipeline, not `pandawork deploy`.
|
|
14
14
|
|
|
15
15
|
## Refresh Managed Guidance
|
|
16
16
|
|
|
17
17
|
If this workspace's exported guidance looks stale or a newly added skill is
|
|
18
|
-
missing, run `
|
|
18
|
+
missing, run `pandawork workspace sync-assets` from the workspace root. See
|
|
19
19
|
`skills/workspace-guidance-refresh/SKILL.md` for the managed refresh flow.
|
|
20
20
|
|
|
21
21
|
## Workspace MCP
|
|
22
22
|
|
|
23
|
-
The
|
|
23
|
+
The PandaWork workspace MCP server exposes read-only context tools (workspace
|
|
24
24
|
snapshot, schema status, capability inventory, deploy status, and a workspace
|
|
25
25
|
doctor; tool names are prefixed `minutework_`). Prefer these over guessing at
|
|
26
26
|
workspace state. It is wired for Cursor (`.cursor/mcp.json`) and Codex
|
|
27
27
|
(`.codex/config.toml`, loaded for trusted projects); for Claude Desktop, copy
|
|
28
28
|
`mcp/claude-desktop.sample.json`. Refresh all of this with
|
|
29
|
-
`
|
|
29
|
+
`pandawork workspace sync-assets`.
|
|
30
30
|
|
|
31
31
|
## Skills
|
|
32
32
|
|
|
33
|
-
This workspace includes
|
|
33
|
+
This workspace includes PandaWork architecture skills under `skills/`. Your IDE
|
|
34
34
|
coding agent can use them as reference: browse `skills/` and read the relevant
|
|
35
35
|
`SKILL.md` when a topic matches your task. In Claude Code these skills load
|
|
36
36
|
automatically and `/skill-name` invokes one directly; other agents (Codex,
|
|
@@ -39,7 +39,7 @@ Cursor) can open the files directly or ask "What skills are available?".
|
|
|
39
39
|
## Project Orientation Fast Path
|
|
40
40
|
|
|
41
41
|
When the user asks broad context questions like "what is this project about?",
|
|
42
|
-
"what can we build with
|
|
42
|
+
"what can we build with PandaWork?", "can we build our own product or make an
|
|
43
43
|
existing product agentic?", "how do OSS products fit?", or "what is the
|
|
44
44
|
ontology/network effect?", do not wait for them to name skills one by one. Read
|
|
45
45
|
`skills/project-overview-and-strategy/SKILL.md` first, then pull the routed
|
|
@@ -108,7 +108,7 @@ a concrete backend responsibility such as:
|
|
|
108
108
|
- Builder may adopt open-source libraries, frameworks, and products inside the
|
|
109
109
|
sandbox when that produces a better result than bespoke code.
|
|
110
110
|
- Prefer this solution order before writing greenfield code:
|
|
111
|
-
- existing
|
|
111
|
+
- existing PandaWork substrate
|
|
112
112
|
- reviewed capability skill or `catalog_native`
|
|
113
113
|
- app-pack/schema/flow extension
|
|
114
114
|
- adopt OSS when it clearly fits
|
|
@@ -118,11 +118,11 @@ a concrete backend responsibility such as:
|
|
|
118
118
|
- If a strong OSS product already solves the problem well, prefer integrating,
|
|
119
119
|
wrapping, or governing it instead of rebuilding it from scratch.
|
|
120
120
|
- Never treat imported OSS as a direct runtime install contract; normalize it
|
|
121
|
-
into governed
|
|
121
|
+
into governed PandaWork artifacts or keep it external through `attached_app`.
|
|
122
122
|
|
|
123
123
|
## Compose Before Rebuild
|
|
124
124
|
|
|
125
|
-
- Compose shared
|
|
125
|
+
- Compose shared PandaWork substrate first: baseline capabilities, runtime
|
|
126
126
|
primitives, reviewed capability skills, app packs, overlays, and hosted
|
|
127
127
|
publication flows.
|
|
128
128
|
- For external collaboration, start from the native substrate: shadow tenant,
|
|
@@ -234,7 +234,7 @@ a concrete backend responsibility such as:
|
|
|
234
234
|
the property uses `runtime_local_sidecar`; publish immutable runtime content
|
|
235
235
|
first.
|
|
236
236
|
- Do not treat `attached_app` as a third serving mode; keep the foreign renderer
|
|
237
|
-
and deploy pipeline external while
|
|
237
|
+
and deploy pipeline external while PandaWork governs drafts, approvals, and
|
|
238
238
|
publish actions.
|
|
239
239
|
- Do not invent a separate guest-account or inbox-routing model when the
|
|
240
240
|
existing shadow identity, alias, route, and thread substrate fits.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Builder Skills
|
|
2
2
|
|
|
3
|
-
Place focused
|
|
3
|
+
Place focused PandaWork architecture skills here.
|
|
4
4
|
|
|
5
5
|
These files are part of the canonical Builder common bundle and are allowlisted
|
|
6
6
|
for developer-local export. Skills are shared across all engine renderers.
|
|
@@ -7,12 +7,12 @@ description: "Deciding the shipped product shape, choosing between tenant-app an
|
|
|
7
7
|
|
|
8
8
|
An `app pack` is the shipped product unit.
|
|
9
9
|
|
|
10
|
-
- Compose shared
|
|
10
|
+
- Compose shared PandaWork substrate first: baseline capabilities, runtime
|
|
11
11
|
primitives, reviewed capability skills, app packs, overlays, and hosted
|
|
12
12
|
publication flows.
|
|
13
13
|
- Templates are governed starters, not the full limit of what Builder may use.
|
|
14
14
|
- Builder may adopt open-source libraries, frameworks, and products inside the
|
|
15
|
-
sandbox when that reduces bespoke code and still preserves the
|
|
15
|
+
sandbox when that reduces bespoke code and still preserves the PandaWork
|
|
16
16
|
contract boundaries.
|
|
17
17
|
- Start with declarative schema/manifests and add code surfaces only when needed.
|
|
18
18
|
- Use `tenant-app` for the combined public-site plus private-app web surface.
|
|
@@ -42,7 +42,7 @@ An `app pack` is the shipped product unit.
|
|
|
42
42
|
- Public-site authoring should stay CMS/runtime-backed, while anonymous live
|
|
43
43
|
delivery should prefer published snapshots.
|
|
44
44
|
- Prefer this decision order before writing greenfield code:
|
|
45
|
-
- reuse existing
|
|
45
|
+
- reuse existing PandaWork substrate or a reviewed capability skill
|
|
46
46
|
- extend app-pack/schema/flow surfaces
|
|
47
47
|
- adopt a strong OSS library or product when it clearly fits
|
|
48
48
|
- use `attached_app` when the foreign system should stay its own subsystem
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: capability-gap-reporting
|
|
3
|
-
description: "A request does not cleanly fit current
|
|
3
|
+
description: "A request does not cleanly fit current PandaWork substrate and a capability gap needs to be recorded."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Capability Gap Reporting
|
|
7
7
|
|
|
8
8
|
Use this skill when a generated workspace discovers that the requested
|
|
9
|
-
implementation does not cleanly fit current
|
|
9
|
+
implementation does not cleanly fit current PandaWork substrate.
|
|
10
10
|
|
|
11
11
|
- Record architecture gaps in `.minutework/runtime/capability-gap-report.json`.
|
|
12
12
|
- Keep the report sanitized and tenant-safe. Do not include secrets, raw
|
|
@@ -52,5 +52,5 @@ implementation does not cleanly fit current MinuteWork substrate.
|
|
|
52
52
|
- `attached_app` when the right home is an attached-app integration surface
|
|
53
53
|
rather than shared core substrate.
|
|
54
54
|
- Prefer one concrete gap per missing shared capability.
|
|
55
|
-
- Use gap reports to tell humans where
|
|
55
|
+
- Use gap reports to tell humans where PandaWork needs new substrate. Do not
|
|
56
56
|
treat them as automatic implementation instructions.
|
|
@@ -8,10 +8,10 @@ description: "Reasoning from a CLI-generated Builder workspace rather than the m
|
|
|
8
8
|
Use this skill when reasoning from a CLI-generated Builder workspace rather than
|
|
9
9
|
the monorepo or a live tenant runtime.
|
|
10
10
|
|
|
11
|
-
- A generated workspace is a developer-local authoring client of
|
|
11
|
+
- A generated workspace is a developer-local authoring client of PandaWork, not
|
|
12
12
|
the runtime itself.
|
|
13
13
|
- Treat these as separate surfaces with different trust boundaries:
|
|
14
|
-
- developer-local broker/orchestrator (`
|
|
14
|
+
- developer-local broker/orchestrator (`pandawork session ...`)
|
|
15
15
|
- runtime-local Builder host inside the tenant runtime
|
|
16
16
|
- runtime-local non-coding assistant inside the tenant product
|
|
17
17
|
- The clearest layering model is:
|
|
@@ -27,7 +27,8 @@ the monorepo or a live tenant runtime.
|
|
|
27
27
|
`tenant-app` or `sidecar`. It is a direct platform API client that consumes
|
|
28
28
|
the platform native-token API (`/api/v1/native/...`) directly with a
|
|
29
29
|
platform-issued native session token, rather than the `tenant-app` BFF cookie
|
|
30
|
-
session.
|
|
30
|
+
session. The mobile starter remains npm-owned standalone app code and should
|
|
31
|
+
not be added to the generated root `pnpm-workspace.yaml`.
|
|
31
32
|
- If the `mobile` starter is enabled (`starters.mobile.enabled`), read
|
|
32
33
|
`standalone-mobile-client/SKILL.md` before proposing the mobile surface.
|
|
33
34
|
- `vuilder-public-site` is a Vuilder-owned public-site authoring workspace for
|
|
@@ -17,7 +17,7 @@ Use this skill when choosing between configuration, app-pack changes, overlays,
|
|
|
17
17
|
- Durable tenant behavior should usually compile to governed app-pack artifacts,
|
|
18
18
|
not ad hoc backend code.
|
|
19
19
|
- Use `attached_app` when a mature foreign system should remain its own
|
|
20
|
-
subsystem and
|
|
20
|
+
subsystem and PandaWork should compile a governed control surface around it.
|
|
21
21
|
- Use `external_repo_intake` only when no reviewed capability skill or cleaner
|
|
22
22
|
`attached_app` path fits. Any repo intake must stay inside the bounded Builder
|
|
23
23
|
sandbox.
|
|
@@ -26,7 +26,7 @@ Use this skill when choosing between configuration, app-pack changes, overlays,
|
|
|
26
26
|
- If strong OSS already exists, prefer adopting or governing it before starting
|
|
27
27
|
a greenfield rebuild.
|
|
28
28
|
- `catalog_native` is the preferred fast path for reusable solutions that can
|
|
29
|
-
compile directly to standard
|
|
29
|
+
compile directly to standard PandaWork artifacts.
|
|
30
30
|
- For generated workspaces, keep the decision order explicit:
|
|
31
31
|
- reuse what already exists
|
|
32
32
|
- prefer `catalog_native` or reviewed-skill composition when available
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: openclaw-skill-importer
|
|
3
|
-
description: "Importing OpenClaw or other third-party skill or plugin material into governed
|
|
3
|
+
description: "Importing OpenClaw or other third-party skill or plugin material into governed PandaWork artifacts."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# OpenClaw Skill Importer
|
|
7
7
|
|
|
8
8
|
Imported third-party skill text is source material, not executable authority.
|
|
9
9
|
|
|
10
|
-
- Translate imported OpenClaw material into governed
|
|
10
|
+
- Translate imported OpenClaw material into governed PandaWork artifacts before using it.
|
|
11
11
|
- Imported OSS can be used even when it is not pre-baked into a template, but
|
|
12
12
|
templates remain the preferred starter path when they already fit.
|
|
13
13
|
- Use `layering-and-import-modes/SKILL.md` to choose the landing shape:
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: project-overview-and-strategy
|
|
3
|
-
description: "Broad project questions: what this workspace is, what
|
|
3
|
+
description: "Broad project questions: what this workspace is, what PandaWork can build, agentic apps, OSS adoption, ontology, or network effects."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Project Overview And Strategy
|
|
@@ -8,7 +8,7 @@ description: "Broad project questions: what this workspace is, what MinuteWork c
|
|
|
8
8
|
Use this skill before answering broad orientation or strategy questions such as:
|
|
9
9
|
|
|
10
10
|
- "What is this project about?"
|
|
11
|
-
- "What can we build with
|
|
11
|
+
- "What can we build with PandaWork?"
|
|
12
12
|
- "Can we build our own product or make an existing product agentic?"
|
|
13
13
|
- "How do OSS products fit?"
|
|
14
14
|
- "What is the ontology or network effect?"
|
|
@@ -48,14 +48,14 @@ needed:
|
|
|
48
48
|
|
|
49
49
|
## Compact Project Answer
|
|
50
50
|
|
|
51
|
-
|
|
52
|
-
extending
|
|
51
|
+
PandaWork Builder is a governed local authoring workspace for building or
|
|
52
|
+
extending PandaWork app packs. An app pack is the product unit. The workspace
|
|
53
53
|
usually composes schemas, manifests, `mw.core.site`, runtime capabilities,
|
|
54
54
|
agents, overlays, and published-web flows before writing bespoke code.
|
|
55
55
|
|
|
56
|
-
|
|
56
|
+
PandaWork supports two legitimate paths:
|
|
57
57
|
|
|
58
|
-
- Build a product natively on
|
|
58
|
+
- Build a product natively on PandaWork.
|
|
59
59
|
- Wrap an existing product or OSS system with a governed, agentic control
|
|
60
60
|
surface.
|
|
61
61
|
|
|
@@ -75,7 +75,7 @@ separate client experiences.
|
|
|
75
75
|
|
|
76
76
|
## Strategic Positioning
|
|
77
77
|
|
|
78
|
-
|
|
78
|
+
PandaWork is most differentiated when identity, shared meaning, external
|
|
79
79
|
collaboration, AI agents, and foreign systems participate in the same governed
|
|
80
80
|
substrate:
|
|
81
81
|
|
|
@@ -92,7 +92,7 @@ substrate:
|
|
|
92
92
|
deployed, and use sidecar bridge code plus runtime agents/tool packs to make
|
|
93
93
|
it governed and agentic.
|
|
94
94
|
- Build-native is appropriate when the capability is central, reusable, and
|
|
95
|
-
should become
|
|
95
|
+
should become PandaWork substrate. Greenfield is last after existing
|
|
96
96
|
substrate, reviewed skills, app-pack extension, OSS adoption, and
|
|
97
97
|
`attached_app` have been considered.
|
|
98
98
|
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: published-web-and-mw-core-site
|
|
3
|
-
description: "Public-site delivery, published-web flows, mw.core.site baseline, or the default
|
|
3
|
+
description: "Public-site delivery, published-web flows, mw.core.site baseline, or the default PandaWork site model."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Published Web And mw.core.site
|
|
7
7
|
|
|
8
8
|
Use this skill when the request touches public-site delivery, published-web
|
|
9
|
-
flows, or the default
|
|
9
|
+
flows, or the default PandaWork site model.
|
|
10
10
|
|
|
11
11
|
- Treat `mw.core.site` as a runtime baseline capability that already exists.
|
|
12
12
|
- For Vuilder-owned public websites, read
|
|
@@ -87,11 +87,16 @@ generated Builder workspace.
|
|
|
87
87
|
- Current active primitives by family:
|
|
88
88
|
- `records`: `records.query`, `records.upsert`
|
|
89
89
|
- `workflow`: `workflow.run_action`, `workflow.schedule_timer`,
|
|
90
|
-
`workflow.resume_checkpoint`
|
|
90
|
+
`workflow.resume_checkpoint`, `workflow.cancel_on_thread_activity`
|
|
91
91
|
- `projection`: `projection.publish_receipt`
|
|
92
92
|
- `integrations`: `integrations.query_provider`,
|
|
93
93
|
`integrations.execute_automation`
|
|
94
94
|
- `communication`: `communication.send_email`, `communication.send_sms`
|
|
95
|
+
- `consent`: `consent.check_channel`
|
|
96
|
+
- `scheduling`: `scheduling.book_appointment`
|
|
97
|
+
- `discovery`: `discovery.request_proposal`
|
|
98
|
+
- `voice`: `voice.initiate_call`, `voice.hangup_call`,
|
|
99
|
+
`voice.get_call_status`
|
|
95
100
|
- `ontology`: `ontology.resolve_local`, `ontology.propose_candidate`
|
|
96
101
|
- `command_exec`: `command_exec.run_template`
|
|
97
102
|
<!-- builder-doc-sync:active-primitives:end -->
|
|
@@ -14,6 +14,10 @@ The answer is yes, and the shape is fixed. Do not flip-flop on it.
|
|
|
14
14
|
- A native mobile app is a **standalone-client exception**. It is authored in
|
|
15
15
|
the `mobile` starter (`destinationDirectory: mobile`), enabled via the
|
|
16
16
|
workspace config key `starters.mobile = { enabled: true, path: "mobile" }`.
|
|
17
|
+
- The `mobile` starter is npm-owned standalone app code even when generated
|
|
18
|
+
beside `tenant-app` in a root pnpm workspace. Run mobile commands from
|
|
19
|
+
`mobile/` with `npm install` and `npx expo start`; do not add `mobile` to the
|
|
20
|
+
root `pnpm-workspace.yaml`.
|
|
17
21
|
- It is **not** part of `tenant-app`, and **not** part of `sidecar`. Do not put
|
|
18
22
|
native code, Expo config, or React Native screens inside either of those
|
|
19
23
|
surfaces.
|
|
@@ -31,6 +35,9 @@ The answer is yes, and the shape is fixed. Do not flip-flop on it.
|
|
|
31
35
|
tokens after browser-assisted login or a device flow
|
|
32
36
|
(`reference/mwv3-dj6-docs/auth_and_credential_contract.md`, Rule 7).
|
|
33
37
|
- The app reads the platform base URL from `EXPO_PUBLIC_MW_PLATFORM_BASE_URL`.
|
|
38
|
+
In local development the starter defaults to `http://127.0.0.1:8000` so a
|
|
39
|
+
fresh scaffold can boot before `.env` exists; set the env var for physical
|
|
40
|
+
devices, tunneled platforms, deployed platforms, and anything shipped.
|
|
34
41
|
|
|
35
42
|
## Endpoints (shipped)
|
|
36
43
|
|
|
@@ -102,4 +109,4 @@ boundary.
|
|
|
102
109
|
- The `mobile` starter is **init-only**. Scaffolding it lands the app in the
|
|
103
110
|
workspace; it does not deploy it.
|
|
104
111
|
- Distribution is the developer's own pipeline: EAS Build, TestFlight, and the
|
|
105
|
-
Play Store. It is **not** `
|
|
112
|
+
Play Store. It is **not** `pandawork deploy`.
|