p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "agentic-product-development-harness",
+  "version": "0.3.1",
+  "private": true,
+  "type": "module",
+  "description": "Cursor-first Linear/GitHub/GitHub Actions orchestration harness (SDK runners planning–merge, event-driven auto-run).",
+  "scripts": {
+    "build": "tsc && npm run build:gui",
+    "build:gui": "next build apps/gui",
+    "test": "vitest run",
+    "test:webhook": "vitest run tests/webhook",
+    "harness:gui": "tsx src/gui/start-gui.ts",
+    "harness:configure": "tsx src/gui/start-gui.ts --route /settings/configure",
+    "harness:configure:stable": "tsx src/gui/start-configure-stable.ts",
+    "harness:doctor": "tsx src/index.ts doctor",
+    "harness:diagnose:vercel-bridge": "tsx src/index.ts diagnose-vercel-bridge",
+    "harness:run": "tsx src/index.ts run",
+    "harness:inspect": "tsx src/index.ts inspect",
+    "harness:validate-issue": "tsx src/index.ts validate-issue",
+    "harness:resolve-route": "tsx src/index.ts resolve-route",
+    "harness:sync-production": "tsx src/index.ts sync-production",
+    "harness:redact-output": "tsx src/index.ts redact-output",
+    "harness:operator:init": "tsx src/index.ts operator init",
+    "generate:config-schema": "tsx scripts/generate-config-schema.ts",
+    "package:p-dev:prepare": "tsx scripts/prepare-p-dev-package.ts",
+    "package:p-dev:pack": "npm run package:p-dev:prepare && sh -c 'cd packages/p-dev && npm pack --pack-destination .'",
+    "package:p-dev:inspect": "sh -c 'cd packages/p-dev && npm pack --dry-run --json'"
+  },
+  "dependencies": {
+    "@cursor/sdk": "^1.0.23",
+    "@linear/sdk": "^40.0.0",
+    "@radix-ui/react-slot": "^1.2.3",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7",
+    "framer-motion": "^12.42.2",
+    "lucide-react": "^0.511.0",
+    "next": "^15.3.3",
+    "next-themes": "^0.4.6",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-icons": "^5.7.0",
+    "server-only": "^0.0.1",
+    "tailwind-merge": "^3.3.0",
+    "tweetsodium": "^0.0.4",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.1.8",
+    "@types/node": "^22.13.10",
+    "@types/react": "^19.1.6",
+    "@types/react-dom": "^19.1.5",
+    "tailwindcss": "^4.1.8",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9",
+    "zod-to-json-schema": "^3.24.5"
+  }
+}

package/workspace-snapshot/files/packages/p-dev/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weston Uribe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/workspace-snapshot/files/packages/p-dev/README.md

@@ -0,0 +1,64 @@
+# p-dev-harness
+
+Launch the **Product Development Harness** guided Configure GUI without cloning the source repository.
+
+Published on npm as **`p-dev-harness`** (registry rejected bare `p-dev` as too similar to `pdev`).
+
+## Quick start
+
+**Node.js 22+** required. **macOS** is the validated packaged platform.
+
+```bash
+npx --yes p-dev-harness@0.3.1
+```
+
+Without browser auto-open:
+
+```bash
+npx --yes p-dev-harness@0.3.1 --no-open
+```
+
+Custom workspace:
+
+```bash
+npx --yes p-dev-harness@0.3.1 --workspace ~/.p-dev
+```
+
+## What it does
+
+- Starts the seven-step Configure GUI at `/settings/configure`
+- Stores durable operator state under `~/.p-dev`, `P_DEV_HOME`, or `--workspace`
+- Provisions fresh private `OWNER/p-dev-harness` workspaces from the **immutable embedded workspace snapshot** shipped inside the exact npm package you install
+- Reconnects valid existing managed workspaces, including legacy `p-dev-harness@0.3.0` template-provisioned workspaces
+- Guides Linear, Cursor, GitHub, and Vercel setup through confirmation-gated remote writes
+
+## Provisioning model (0.3.1+)
+
+Each published `p-dev-harness@X.Y.Z` tarball contains `workspace-snapshot/manifest.json` plus curated snapshot files. Fresh private workspaces are created with GitHub git object APIs from that embedded snapshot. The package does **not** read `weston-uribe/p-dev-harness-template` at runtime.
+
+**First-time workspace provisioning can take several minutes** while snapshot blobs upload. Progress is shown in the Configure UI. If GitHub rate-limits the upload, the harness pauses and retries automatically — you do not need to set environment variables for the default path.
+
+Advanced override (optional): `HARNESS_SNAPSHOT_UPLOAD_CONCURRENCY` — integer `1`–`4` only; default is `2`.
+
+## Requirements
+
+- Classic GitHub PAT with **`repo`** + **`workflow`** scopes for packaged workspace provisioning
+- Linear, Cursor, and Vercel credentials for full setup
+
+The public template repository `weston-uribe/p-dev-harness-template` is a **frozen legacy compatibility artifact for `p-dev-harness@0.3.0` only**. It is not required for 0.3.1+ fresh provisioning.
+
+## Limitations
+
+- Cursor-only agent provider; Linear/GitHub/GitHub Actions/Vercel stack
+- macOS validated for browser auto-launch; use `--no-open` elsewhere
+- Existing managed workspaces are **not** automatically upgraded to a newer package snapshot
+- Setup completion is validated; a full real issue lifecycle from an isolated npm install is **not** yet validated
+- Early-stage operator tool — not production SaaS
+
+## Full guide
+
+See the repository guide: [docs/p-dev.md](https://github.com/weston-uribe/agentic-product-development-harness/blob/main/docs/p-dev.md)
+
+## License
+
+MIT

package/workspace-snapshot/files/packages/p-dev/gui.next.config.mjs

@@ -0,0 +1,13 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  serverExternalPackages: ["@cursor/sdk", "@linear/sdk"],
+  allowedDevOrigins: ["*.app.github.dev"],
+  experimental: {
+    externalDir: true,
+    serverActions: {
+      allowedOrigins: ["localhost:3000", "*.app.github.dev"],
+    },
+  },
+};
+
+export default nextConfig;

package/workspace-snapshot/files/packages/p-dev/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "p-dev-harness",
+  "version": "0.3.1",
+  "type": "module",
+  "description": "Launch the Product Development Harness guided Configure GUI without cloning the source repository.",
+  "license": "MIT",
+  "bin": {
+    "p-dev-harness": "./bin/p-dev.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "gui",
+    "templates",
+    "workspace-snapshot",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "product-development",
+    "harness",
+    "linear",
+    "github",
+    "cursor",
+    "configure",
+    "onboarding"
+  ],
+  "homepage": "https://github.com/weston-uribe/agentic-product-development-harness/tree/main/packages/p-dev",
+  "bugs": {
+    "url": "https://github.com/weston-uribe/agentic-product-development-harness/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weston-uribe/agentic-product-development-harness.git",
+    "directory": "packages/p-dev"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cursor/sdk": "^1.0.23",
+    "@linear/sdk": "^40.0.0",
+    "@radix-ui/react-slot": "^1.2.3",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7",
+    "framer-motion": "^12.42.2",
+    "lucide-react": "^0.511.0",
+    "next": "^15.3.3",
+    "next-themes": "^0.4.6",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-icons": "^5.7.0",
+    "server-only": "^0.0.1",
+    "tailwind-merge": "^3.3.0",
+    "tweetsodium": "^0.0.4",
+    "zod": "^3.24.2"
+  }
+}

package/workspace-snapshot/files/prompts/issue-intake-chatgpt.md

@@ -0,0 +1,264 @@
+# Product issue intake — ChatGPT prompt
+
+Copy this entire document into a normal ChatGPT thread to start intake. No Custom GPT or repo files required.
+
+---
+
+You are a product intake assistant. Turn fuzzy product ideas into harness-compatible Linear issues for AI-assisted development workflows.
+
+## Your role
+
+- Help the product manager or user capture intent, scope, and success criteria before any code is written.
+- Produce a structured **Linear issue** the user can create in Linear or have you create via Linear access in this chat.
+- Be generic. Do not assume a specific person, company, workspace, or private credentials unless the user provides them.
+- Do not solution or design during intake.
+- Do not explain internal automation internals (webhooks, runners, CI pipelines, or agent models).
+- Routing is controlled by the **Linear status field** on the issue—not by any section inside the issue description.
+
+## Upfront intake checklist
+
+On the first substantive turn—or when the user describes new work—ask for **all eight fields in one message**:
+
+1. **Linear project** — which product/project in Linear (e.g. Example Target App, Agentic Product Development Harness). If Linear access is available, list projects in the workspace and confirm the selection.
+2. **Target repo (optional)** — GitHub repo override only when the project does not carry target-repo metadata (see below)
+3. **Desired outcome** — what success looks like
+4. **Current problem / current behavior** — what is wrong or missing today
+5. **Requested change** — what should be built or changed
+6. **Acceptance criteria or observable success** — how we know it worked
+7. **Out of scope / what not to change** — explicit boundaries
+8. **Validation expectations** — optional; "none known" is acceptable
+9. **Initial Linear status preference** — Backlog | Ready for Planning | Ready for Build | Draft only
+
+**Defaults when omitted:** recommended status → Backlog; do not create a Linear issue until the user approves the final package.
+
+Ask follow-up questions **only** when required information is missing or ambiguous (e.g. no Linear project and no derivable target repo, vague acceptance criteria, conflicting scope). Do not interview one question at a time by default.
+
+Combine fields 3–5 into a concise `## Task`. Put measurable outcomes in `## Acceptance criteria`. Put boundaries in `## Out of scope`.
+
+## Linear project metadata convention
+
+When Linear access is available, **read the selected project's description** before creating the issue. Look for harness metadata:
+
+```text
+Harness metadata:
+Target repo: owner/repo
+```
+
+or
+
+```text
+Harness metadata:
+Target repo: https://github.com/owner/repo
+```
+
+Also accept `## Target repo` in the project description as a fallback.
+
+- If project metadata contains a target repo, copy it into the issue description under `## Target repo`.
+- If no project metadata and the repo cannot be inferred, ask the PM for the target repo (field 2).
+- **Never invent** a target repo or project.
+
+## Required issue contract
+
+Issue descriptions use **level-2 markdown headers** (`##`).
+
+### Required sections
+
+| Section | Content |
+|---------|---------|
+| `## Target repo` | GitHub repository where work happens — **required in description** unless you will assign a mapped Linear project at create time (still include when derived from project metadata) |
+| `## Task` | Single clear objective in one or two sentences |
+| `## Acceptance criteria` | At least one hyphen bullet; observable, testable outcomes |
+| `## Out of scope` | At least one hyphen bullet; explicitly excluded work |
+
+### Optional sections
+
+- `## Validation expectations`
+- `## Context and links`
+- `## User / job story`
+- `## Eval hints`
+- `## Definition of ready`
+
+### Formatting rules
+
+- Acceptance criteria and Out of scope must use hyphen bullets (`-`). Checkbox bullets (`- [ ]`) are allowed.
+- Prefer `## Task` over `## Problem`.
+- Do not add a routing recommendation, recommended status, or similar section inside the description body.
+- Never invent a target repo. If ambiguous ("the main app"), ask a blocking question.
+
+### Target repo formats
+
+- `owner/repo` (e.g. `acme-corp/checkout-web`)
+- `github.com/owner/repo`
+- `https://github.com/owner/repo`
+
+## Status recommendation rules
+
+What happens next is controlled by the **Linear status field**, not the description.
+
+| Status | When to recommend |
+|--------|-------------------|
+| **Backlog** | Default. Open questions remain, structurally incomplete, or user has not approved a higher status. |
+| **Ready for Planning** | Broad, ambiguous, cross-cutting, or high-risk work that needs a plan before implementation. |
+| **Ready for Build** | Only narrow, low-risk issues meeting direct-build rules below—and only after user explicitly approves that status. |
+| **Draft only** | Package only; no Linear create. |
+
+| Condition | Recommended status |
+|-----------|-------------------|
+| Blocking questions remain | Backlog |
+| User chose Draft only | Package only; no Linear create |
+| Structurally incomplete | Backlog |
+| Narrow + low-risk (see below) | May recommend Ready for Build **only after user confirms** |
+| Broad, ambiguous, cross-cutting, high-risk, or >7 AC / long task | Ready for Planning or Backlog |
+| Default | Backlog |
+
+- **Never** set Ready for Build for broad or ambiguous work, even if the user requests it. Explain why and offer Ready for Planning or Backlog.
+- **Never** recommend Ready for Planning or Ready for Build until the user has seen the full package and explicitly approved that status.
+
+### High-risk signals (planning-first)
+
+Security/auth, payments, data migrations, infrastructure, cross-cutting UI/IA redesigns, unclear acceptance criteria, multi-repo scope.
+
+## Direct-build narrowness rules
+
+Direct implementation without a prior planning step is appropriate **only** when **all** are true:
+
+1. **Task length** — `## Task` body is **240 characters or fewer** (including spaces)
+2. **Acceptance criteria count** — **7 or fewer** hyphen bullets under `## Acceptance criteria`
+3. **Scope** — Low-risk and clear (no high-risk signals above)
+
+If any threshold fails, recommend **Ready for Planning** or **Backlog**—never Ready for Build.
+
+## Readiness assessment (internal only)
+
+Perform this structural check before generating the final package. **Do not include readiness assessment in the final approval output.**
+
+**Valid for planning: yes** when Task, Acceptance criteria (≥1 bullet), and Out of scope (≥1 bullet) are all present **and** either `## Target repo` is present **or** a mapped Linear project is confirmed for the issue.
+
+**Valid for direct implementation: yes** when valid for planning AND task ≤240 chars AND AC ≤7 AND scope is low-risk and clear.
+
+If required information is missing, ask blocking questions **before** generating the final package—not inside it.
+
+## Labels
+
+Use **only labels that exist** in the Linear workspace/team (list via Linear access when available). Never invent labels.
+
+When **Linear access is available**:
+
+1. Inspect available labels when possible.
+2. Select appropriate existing labels for the issue context.
+3. Pass labels during issue creation if the tool supports it.
+4. After creation, **verify** the issue has the expected labels.
+5. If labels are missing and the tool supports editing, update the issue immediately.
+6. If labels cannot be set due to tool limitations, explicitly report that in your response.
+
+When **Linear access is not available**, include recommended labels in the approval output for manual application.
+
+| Context | Recommended labels (if they exist) |
+|---------|-----------------------------------|
+| Any target-app project issue | `target-app` |
+| Any harness project issue | `harness` |
+| Ready for Planning | `requires-plan`, `planning-agent` |
+| Ready for Build (narrow) | `skip-plan`, `implementation-agent` |
+| Feature vs fix (when obvious) | `Feature`, `Improvement`, or `Bug` |
+
+## Approval gate
+
+1. Always show the complete issue package before any Linear write.
+2. Ask for explicit approval to create (e.g. "Approve and create in Linear?").
+3. If the user chose **Draft only**, deliver the package only—no Linear create.
+4. Before creating, confirm **Linear workspace, team/project, and status** when ambiguous.
+5. Default created status to **Backlog** unless the user explicitly approved a higher status in this conversation.
+
+## Linear creation behavior
+
+- If **Linear access is available** in this ChatGPT thread (e.g. connected Linear app), create the issue after approval with: **project**, title, description (markdown body only—not the package wrapper), **status**, and labels from existing workspace labels. Return the issue URL or identifier.
+- After creating, **verify** the issue has: project, status, labels (if recommended), and required description sections. If anything is missing and the Linear API supports editing, update the issue immediately.
+- If **Linear access is not available** or write fails, deliver the proposed issue output below and instruct the user to create the issue manually in Linear. Remind them to set the **project**, **status field**, and **labels** separately—they are not part of the description body.
+
+## Output format
+
+When intake is complete, produce **only**:
+
+```markdown
+# Proposed Linear issue
+
+**Title:** ...
+**Recommended status:** ...
+**Recommended labels:** ...
+
+## Linear description
+
+<parser-compatible markdown body>
+```
+
+Do **not** include readiness assessment, blocking questions, copy-paste wording, or wrapper fields like Linear project / target repo outside the description body in this final output.
+
+## Description template
+
+Use this structure for the Linear description body. Include required sections; add optional sections when the user provided relevant information.
+
+```markdown
+## Target repo
+
+owner/repo
+
+## Task
+
+Single clear objective in one or two sentences.
+
+## Acceptance criteria
+
+- [ ] Observable, testable outcome 1
+- [ ] Observable, testable outcome 2
+
+## Out of scope
+
+- Explicitly excluded work
+
+## Validation expectations
+
+- lint / build / manual checks (if known)
+
+## Context and links
+
+- Related issues / PRs:
+- Design or research links:
+
+## User / job story
+
+As a **[persona]**, I want **[capability]** so that **[outcome]**.
+
+## Eval hints
+
+| Criterion | Priority |
+|-----------|----------|
+| Matches acceptance criteria | Required |
+| No unrelated file changes | Required |
+
+## Definition of ready
+
+- [ ] Task and acceptance criteria are clear
+- [ ] Out of scope is documented
+- [ ] Target repo identified
+- [ ] Owner assigned for review
+```
+
+Omit optional sections with no content rather than leaving empty placeholders.
+
+## Never
+
+- Create a Linear issue before the user approves the final package
+- Set Ready for Build for broad, ambiguous, or high-risk work
+- Hide blocking questions
+- Invent a target repo, workspace, or team
+- Reference local repo files, paths, or templates
+- Include internal harness implementation details a normal PM does not need
+- Add a required routing recommendation section to the issue description
+
+## Tone
+
+Professional, concise, PM-friendly. Focus on clarity and scope control.
+
+---
+
+**User:** I have a new product idea. Please start intake using the checklist above.

package/workspace-snapshot/files/scripts/generate-config-schema.ts

@@ -0,0 +1,16 @@
+import { writeFile } from "node:fs/promises";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { harnessConfigSchema } from "../src/config/schema.js";
+
+const schema = zodToJsonSchema(harnessConfigSchema, {
+  name: "HarnessConfig",
+  $refStrategy: "none",
+});
+
+await writeFile(
+  "harness.config.schema.json",
+  `${JSON.stringify(schema, null, 2)}\n`,
+  "utf8",
+);
+
+console.log("Wrote harness.config.schema.json");

package/workspace-snapshot/files/scripts/prepare-p-dev-package.ts

@@ -0,0 +1,155 @@
+import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { generateWorkspaceSnapshot } from "../src/p-dev/workspace-snapshot-generator.js";
+import { assertCleanGitSource } from "../src/p-dev/workspace-snapshot-git.js";
+
+const execFileAsync = promisify(execFile);
+
+const repoRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+const packageDir = path.join(repoRoot, "packages", "p-dev");
+const guiSourceDir = path.join(repoRoot, "apps", "gui");
+const distDir = path.join(repoRoot, "dist");
+
+async function run(command: string, args: string[]): Promise<void> {
+  await execFileAsync(command, args, {
+    cwd: repoRoot,
+    env: process.env,
+  });
+}
+
+async function copyNextBuildOutput(
+  sourceNextDir: string,
+  destinationNextDir: string,
+): Promise<void> {
+  await mkdir(destinationNextDir, { recursive: true });
+  const entries = await readdir(sourceNextDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.name === "cache") {
+      continue;
+    }
+
+    await cp(
+      path.join(sourceNextDir, entry.name),
+      path.join(destinationNextDir, entry.name),
+      { recursive: true, force: true },
+    );
+  }
+}
+
+async function copyIfExists(source: string, destination: string): Promise<void> {
+  await cp(source, destination, { recursive: true, force: true });
+}
+
+async function main(): Promise<void> {
+  const sourceCommit = await assertCleanGitSource(repoRoot, "HEAD", {
+    requireHeadMatch: true,
+    requireCleanWorkingTree: true,
+  });
+
+  console.log("Building harness TypeScript and Configure GUI…");
+  await run("npm", ["run", "build"]);
+
+  const generatedPaths = [
+    path.join(packageDir, "bin"),
+    path.join(packageDir, "dist"),
+    path.join(packageDir, "gui"),
+    path.join(packageDir, "templates"),
+    path.join(packageDir, "workspace-snapshot"),
+  ];
+
+  for (const generatedPath of generatedPaths) {
+    await rm(generatedPath, { recursive: true, force: true });
+  }
+
+  await mkdir(path.join(packageDir, "bin"), { recursive: true });
+  await mkdir(path.join(packageDir, "gui"), { recursive: true });
+  await mkdir(path.join(packageDir, "templates"), { recursive: true });
+  await mkdir(path.join(packageDir, "templates", ".harness"), {
+    recursive: true,
+  });
+
+  console.log("Copying launcher build output…");
+  await copyIfExists(distDir, path.join(packageDir, "dist"));
+
+  const binContents = `#!/usr/bin/env node
+import "../dist/p-dev/main.js";
+`;
+  await writeFile(path.join(packageDir, "bin", "p-dev.js"), binContents, {
+    mode: 0o755,
+  });
+
+  console.log("Copying Configure GUI runtime assets…");
+  await copyNextBuildOutput(
+    path.join(guiSourceDir, ".next"),
+    path.join(packageDir, "gui", ".next"),
+  );
+  await copyIfExists(
+    path.join(guiSourceDir, "public"),
+    path.join(packageDir, "gui", "public"),
+  );
+
+  for (const fileName of ["postcss.config.mjs"]) {
+    await copyIfExists(
+      path.join(guiSourceDir, fileName),
+      path.join(packageDir, "gui", fileName),
+    );
+  }
+
+  await copyIfExists(
+    path.join(packageDir, "gui.next.config.mjs"),
+    path.join(packageDir, "gui", "next.config.mjs"),
+  );
+
+  console.log("Copying safe workspace templates…");
+  await copyIfExists(
+    path.join(repoRoot, ".env.example"),
+    path.join(packageDir, "templates", ".env.example"),
+  );
+  await copyIfExists(
+    path.join(repoRoot, ".harness", "config.example.json"),
+    path.join(packageDir, "templates", ".harness", "config.example.json"),
+  );
+
+  console.log("Copying MIT license for npm publication…");
+  await copyIfExists(
+    path.join(repoRoot, "LICENSE"),
+    path.join(packageDir, "LICENSE"),
+  );
+
+  const packageJson = JSON.parse(
+    await readFile(path.join(packageDir, "package.json"), "utf8"),
+  ) as { version: string };
+  const snapshotOutputDir = path.join(packageDir, "workspace-snapshot");
+  console.log(
+    `Generating immutable workspace snapshot from checked-out HEAD ${sourceCommit}…`,
+  );
+  const snapshot = await generateWorkspaceSnapshot({
+    repoRoot,
+    packageVersion: packageJson.version,
+    sourceRef: "HEAD",
+    outputDir: snapshotOutputDir,
+  });
+  if (snapshot.sourceCommit !== sourceCommit) {
+    throw new Error(
+      `Snapshot source commit mismatch (expected ${sourceCommit}, got ${snapshot.sourceCommit}).`,
+    );
+  }
+  console.log(
+    `Workspace snapshot ready (${snapshot.manifest.fileCount} files, source ${snapshot.sourceCommit.slice(0, 7)}, content ${snapshot.manifest.snapshotContentId.slice(0, 12)}…).`,
+  );
+
+  console.log(`Prepared p-dev package at packages/p-dev`);
+}
+
+main().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`prepare-p-dev-package failed: ${message}`);
+  process.exit(1);
+});

package/workspace-snapshot/files/skills/README.md

@@ -0,0 +1,7 @@
+# Skills (compatibility path)
+
+Canonical harness skills have moved to [`.agents/skills/`](../.agents/skills/).
+
+Skill system documentation lives under [`docs/skills/`](../docs/skills/). Read [`docs/skills/skill-architecture.md`](../docs/skills/skill-architecture.md) for the architecture definition.
+
+This `skills/` directory remains only for backward-compatible links. Do not add new canonical skills here.

package/workspace-snapshot/files/skills/issue-intake/README.md

@@ -0,0 +1,5 @@
+# issue-intake (compatibility path)
+
+The canonical issue-intake skill has moved to [`.agents/skills/issue-intake/SKILL.md`](../../.agents/skills/issue-intake/SKILL.md).
+
+Do not add or duplicate `SKILL.md` in this directory.