peer-ai 1.0.0-next.0 → 1.0.0-next.1

package/README.md

@@ -27,6 +27,7 @@ npm install --save-dev peer-ai
 | Command | What it does |
 |---------|--------------|
 | [`peer-ai init`](#peer-ai-init) | Sets up Peer AI in a repository: one config file, from what it detects |
+| [`peer-ai migrate`](#peer-ai-migrate) | Moves a project from its copy of v0 onto Peer AI 1.0 |
 | [`peer-ai assess`](#peer-ai-assess) | Maps what the project has and what its stage still needs |
 | [`peer-ai render`](#peer-ai-render) | Connects each AI tool: instructions, the MCP server and the skills |
 | [`peer-ai doctor`](#peer-ai-doctor) | Checks the setup and says how to fix what isn't right |
@@ -76,6 +77,40 @@ It never overwrites an existing `peer-ai.config.json`, and it never assumes anyt
 
 `0` success, `1` refused (a config already exists) or cancelled, `2` a usage error.
 
+## `peer-ai migrate`
+
+Moves a project from v0, when Peer AI was a playbook copied into a `peer-ai/` folder, onto the package ([RFC 0008](../../rfcs/0008-moving-a-v0-project-onto-1-0.md)).
+
+```bash
+npx peer-ai migrate --dry-run
+npx peer-ai migrate
+```
+
+It converts what it can read with certainty:
+
+| From v0 | Into |
+|---------|------|
+| The Project settings table in the workflow driver | `commands.verify`, `tracker`, `repo.branchNaming`, `repo.mergePolicy` and `design.reference` |
+| `phase-config.json` | `models`, each skill's add-ons and notes, and each activity's notes. A phase that says a part is dormant marks it `dormant`. |
+| Markdown files in `docs/standards/` | `standards.documents`, as standards or an addendum, each scoped to its part |
+| `.peer-ai-state.json` | A work item for each ticket in progress. The tracker keeps the rest. |
+
+Then it deletes the `peer-ai/` folder and the state file, takes v0's text out of `CLAUDE.md`, `AGENTS.md` and the other instruction files, maps the project and sets up the AI tools, as `assess` and `render` do.
+
+Nothing is dropped silently. Whatever needs judgement, it copies word for word into `docs/peer-ai-migration.md`: the files the project edited in `peer-ai/`, the text it took out of the instruction files, the settings it couldn't place, and anything it left alone that still names v0. A work item, `migrate-v0`, points there, so your AI tool brings each decision up in the next session.
+
+It tells the files the project changed from v0's own by their fingerprints: a list of every file in every v0 version, which ships with the package.
+
+It never commits. It won't start with uncommitted changes, so the migration is a change of its own: review it, commit it on a branch, and open a pull request. `git restore . && git clean -fd` undoes it all.
+
+### Options
+
+The same as `init`. With `--dry-run`, it prints what it would convert, rewrite, delete and leave for a decision, and changes nothing.
+
+### Exit codes
+
+`0` success, `1` refused (a config already exists, there is no v0 copy, the project isn't in git or has uncommitted changes) or cancelled, `2` a usage error.
+
 ## `peer-ai assess`
 
 Maps what a project already has, and what its stage still needs. Run it on any project, at any point: a brief with no code, a prototype, or a product in production with no documents at all.
@@ -165,7 +200,7 @@ npx peer-ai render
 
 `AGENTS.md` gets the block whenever a tool other than Claude Code is listed, when it already exists, or when `CLAUDE.md` imports it.
 
-The instructions are short: how to work through the MCP server, the project's parts, its commands, its compliance packs and its own rules. The server serves the detail when it's needed, rather than every rule on every turn.
+The instructions are short: how to work through the MCP server, the project's parts, its commands, its compliance packs and its own rules, and the project's settings for models, skills and activities when it has any: the models to use, the add-ons, checklists and notes for each skill, and the files to read and notes for each activity. The server serves the detail when it's needed, rather than every rule on every turn.
 
 ### Skills
 
@@ -308,6 +343,15 @@ Run it after the project's own checks:
 - run: npx peer-ai check
 ```
 
+That uses the version in the project's `package.json`. A project without one, such as a Python or Flutter project, needs Node 24 on the runner and the version `render` pinned:
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 24
+- run: npx -y peer-ai@<version> check
+```
+
 ### Options
 
 | Option | What it does |

package/dist/cli.js

@@ -13,6 +13,7 @@ import { runDoctor } from "./doctor.js";
 import { runFeedback } from "./feedback.js";
 import { serveStdio } from "./mcp.js";
 import { runInit } from "./init.js";
+import { runMigrate } from "./migrate.js";
 import { VERSION } from "./package-info.js";
 import { createTerminalPrompter } from "./prompter.js";
 import { formatReport } from "./report.js";
@@ -23,6 +24,7 @@ const HELP = `peer-ai: from a brief to a shipped product, with any AI tool
 
 Usage:
   peer-ai init [options]      Set up Peer AI in this repository
+  peer-ai migrate [options]   Move a project from its copy of v0 onto Peer AI 1.0
   peer-ai assess [options]    Map what the project has and what its stage still needs
   peer-ai render [options]    Set up each AI tool in the config: instructions and the MCP server
   peer-ai doctor [options]    Check that Peer AI is set up correctly, and how to fix it
@@ -47,6 +49,9 @@ Options for init:
       --tool <tool>           An AI tool you use; repeat for several
                               (${TOOL_IDS.join(", ")})
 
+Options for migrate: the same as init. It never commits, and it won't start on
+uncommitted changes. --dry-run prints what it would do, changing nothing.
+
 Options for assess:
       --target <stage>        Assess against a stage other than the project's own,
                               for example production before a launch
@@ -79,7 +84,8 @@ function oneOf(value, allowed, flag) {
         return value;
     throw new Error(`${flag} must be one of: ${allowed.join(", ")}`);
 }
-async function init(args, io) {
+/** The options init and migrate share. */
+function initOptions(args, io) {
     const { values } = parseArgs({
         args,
         strict: true,
@@ -95,7 +101,7 @@ async function init(args, io) {
     const stage = values.stage === undefined ? undefined : oneOf(values.stage, STAGES, "--stage");
     const team = values.team === undefined ? undefined : oneOf(values.team, ["solo", "team"], "--team");
     const tools = values.tool?.map((tool) => oneOf(tool, TOOL_IDS, "--tool"));
-    return runInit({
+    return {
         cwd: io.cwd,
         yes: values.yes === true,
         dryRun: values["dry-run"] === true,
@@ -103,7 +109,13 @@ async function init(args, io) {
         ...(stage === undefined ? {} : { stage }),
         ...(team === undefined ? {} : { team }),
         ...(tools === undefined ? {} : { tools }),
-    }, io.prompter, io.out);
+    };
+}
+function init(args, io) {
+    return runInit(initOptions(args, io), io.prompter, io.out);
+}
+function migrate(args, io) {
+    return runMigrate(initOptions(args, io), io.prompter, io.out);
 }
 function assess(args, io) {
     const { values } = parseArgs({
@@ -175,6 +187,7 @@ async function mcp(args, io) {
 }
 const COMMANDS = {
     init,
+    migrate,
     assess,
     render,
     doctor,

package/dist/doctor.js

@@ -240,9 +240,11 @@ function checkGit(root) {
 function checkLegacy(root) {
     if (!LEGACY_MARKERS.some((marker) => existsSync(join(root, marker))))
         return [];
-    return [
-        warn("legacy", "The peer-ai/ folder is a copy of the v0 playbook, which Peer AI 1.0 doesn't read.", `Move any changes your project made to it into ${CONFIG_FILE}, then remove it with: git rm -r peer-ai`),
-    ];
+    // migrate builds the config itself, so it only runs before there is one.
+    const fix = existsSync(join(root, CONFIG_FILE))
+        ? `Move any changes your project made to it into ${CONFIG_FILE}, then remove it with: git rm -r peer-ai`
+        : "Run npx peer-ai migrate. It moves what your project changed into the config, and removes the folder.";
+    return [warn("legacy", "The peer-ai/ folder is a copy of the v0 playbook, which Peer AI 1.0 doesn't read.", fix)];
 }
 export function diagnose(root, nodeVersion = process.versions.node, today = new Date(), options = {}) {
     const { check: configCheck, config } = checkConfig(root);

package/dist/init.d.ts

@@ -17,7 +17,7 @@ export interface Output {
     log: (line: string) => void;
     error: (line: string) => void;
 }
-interface Answers {
+export interface Answers {
     name: string;
     description: string;
     tracks: DetectedTrack[];
@@ -26,6 +26,7 @@ interface Answers {
     tools: ToolId[];
 }
 export declare function describeTrack(track: DetectedTrack): string;
+export declare function ask(detected: Detected, prompter: Prompter, title?: string): Promise<Answers>;
+export declare function defaults(detected: Detected, options: InitOptions): Answers;
 export declare function buildConfig(detected: Detected, answers: Answers): Record<string, unknown>;
 export declare function runInit(options: InitOptions, prompter: Prompter | undefined, out: Output): Promise<number>;
-export {};

package/dist/init.js

@@ -42,8 +42,8 @@ function parseStack(text) {
         .map((part) => part.trim().toLowerCase())
         .filter((part) => part !== "");
 }
-async function ask(detected, prompter) {
-    prompter.intro("peer-ai init");
+export async function ask(detected, prompter, title = "peer-ai init") {
+    prompter.intro(title);
     if (detected.tracks.length > 0) {
         prompter.note(detected.tracks.map(describeTrack).join("\n"), "Found in this repository");
     }
@@ -75,7 +75,7 @@ async function ask(detected, prompter) {
     }
     return { name, description, tracks, team, stage, tools };
 }
-function defaults(detected, options) {
+export function defaults(detected, options) {
     return {
         name: options.name ?? detected.name,
         description: detected.description ?? "",

package/dist/migrate.d.ts

@@ -0,0 +1,95 @@
+import { type ActivityId } from "peer-ai-workflow";
+import { type Detected } from "./detect.ts";
+import { type Answers, type InitOptions, type Output } from "./init.ts";
+import { type Prompter } from "./prompter.ts";
+import { type Converted, type Copy, type Fingerprints } from "./v0.ts";
+export declare const NOTES_FILE = "docs/peer-ai-migration.md";
+export declare const MIGRATION_ITEM = "migrate-v0";
+export interface MigrateOptions extends InitOptions {
+    now?: Date;
+    /** The v0 fingerprints to compare against. Tests pass their own. */
+    fingerprints?: Fingerprints;
+}
+/** What git knows about the project, read once before anything changes. */
+export interface RepoState {
+    /** The copy's files git tracks, which it can bring back after they're deleted. */
+    tracked: string[];
+    /** The copy's files git ignores, which migrate leaves where they are. */
+    ignored: string[];
+    /** The commit before the migration, so the notes can point at the files as they were. */
+    base?: string;
+}
+interface Decision {
+    title: string;
+    body: string[];
+}
+interface PlannedItem {
+    id?: string;
+    title: string;
+    stage: "prepare" | "build" | "verify";
+    track?: string;
+    position?: {
+        activity: ActivityId;
+        step: number;
+    };
+    next: string;
+}
+export interface Plan {
+    config: Record<string, unknown>;
+    copy: Copy;
+    converted: Converted[];
+    /** Files rewritten: instructions without v0's text, package.json without v0's scripts. */
+    edits: {
+        path: string;
+        text: string;
+    }[];
+    /** Files deleted outside the copy, each quoted in the notes or rebuilt from git. */
+    removals: string[];
+    /** The copy's tracked files, deleted one by one; its ignored files stay. */
+    copyFiles: string[];
+    decisions: Decision[];
+    /** Whole files kept in the notes as v0 had them, for reference. */
+    kept: {
+        path: string;
+        text: string;
+        info: string;
+    }[];
+    items: PlannedItem[];
+    base?: string;
+}
+/** A fenced block that holds any text, with a fence longer than any inside it. */
+export declare function fenced(text: string, info?: string): string[];
+/** Inline code that holds any text, even text with backticks of its own. */
+export declare function code(text: string): string;
+/** A work item id for a v0 ticket: PROJ-14 stays, #12 becomes PREFIX-12 or ITEM-12. */
+export declare function ticketId(ticket: string, prefix: string | undefined): string | undefined;
+export interface Scripts {
+    text: string;
+    removed: {
+        name: string;
+        command: string;
+    }[];
+}
+/**
+ * package.json without the scripts that only run v0's files. A script that does anything else as
+ * well stays as it is, and is listed for a person.
+ */
+export declare function packageScripts(text: string): {
+    edit?: Scripts;
+    mentions: {
+        name: string;
+        command: string;
+    }[];
+};
+/** Works out everything migrate will do, without changing anything. */
+export declare function planMigration(root: string, detected: Detected, answers: Answers, fingerprints: Fingerprints, repo: RepoState): Plan;
+/** docs/peer-ai-migration.md: what migrate did, and every decision it left. */
+export declare function notesDocument(plan: Plan, today: string): string;
+/** A path that leads outside the project, through a symbolic link on the way or at the end. */
+export declare function escapes(root: string, path: string): boolean;
+/**
+ * Exit code 0 when migrated, or with --dry-run; 1 when it refuses, or when the migration was applied
+ * but a step after it didn't finish; 2 on a usage error.
+ */
+export declare function runMigrate(options: MigrateOptions, prompter: Prompter | undefined, out: Output): Promise<number>;
+export {};