@yagni-app/code-staging 0.1.0-staging.1019.1 → 0.1.0-staging.1020.1

package/dist/extension/index.d.ts

@@ -110,8 +110,8 @@ export { makeSuggestNextWorkTool, defaultNextAction } from "./nextWorkTool.js";
 export type { MakeNextWorkToolOptions, DefaultNextAction, NextActionOption, } from "./nextWorkTool.js";
 export { recordDecision } from "./recordDecisionTool.js";
 export type { RecordDecisionParams } from "./recordDecisionTool.js";
-export { runInitPass, isFreshWorkspace, readRepoIntake, draftEngineering, summarizeDraft, FRESH_BRIEF_MIN_CHARS, } from "./initPass.js";
-export type { RunInitPassDeps, InitPassOutcome, RepoIntake, RepoIntakeFs, RepoAdr, EngineeringDraft, DraftTeam, } from "./initPass.js";
+export { runInitPass, runTeamSetup, registerTeamSetupCommand, isFreshWorkspace, readRepoIntake, draftEngineering, summarizeDraft, FRESH_BRIEF_MIN_CHARS, } from "./initPass.js";
+export type { RunInitPassDeps, InitPassOutcome, RunTeamSetupDeps, TeamSetupOutcome, RepoIntake, RepoIntakeFs, EngineeringDraft, DraftTeam, } from "./initPass.js";
 export { isInitDone, markInitDone, initDoneMarkerFile, _setInitDoneHomeForTest } from "./initDone.js";
 export { brandSystemPrompt, YAGNI_IDENTITY, YAGNI_IDENTITY_DRIVER, BRAND_NAME } from "./branding.js";
 export { attributionHeaders, isDriverCaller, fetchCatalog, getToken, getWorkspaceId, resolveBaseUrl, sanitizeCallerSegment, } from "./config.js";

package/dist/extension/index.js

@@ -16,7 +16,7 @@ import { isDebug } from "./diagnostics.js";
 import { droppedSessionRuns, sessionRunIds } from "./sessionRuns.js";
 import { codeStateHome } from "./stateHome.js";
 import { RerouteNotifier } from "./rerouteNotice.js";
-import { isFreshWorkspace, runInitPass as defaultRunInitPass } from "./initPass.js";
+import { isFreshWorkspace, registerTeamSetupCommand, runInitPass as defaultRunInitPass } from "./initPass.js";
 import { isInitDone as defaultIsInitDone, markInitDone as defaultMarkInitDone } from "./initDone.js";
 import { fetchMcpServers as defaultFetchMcpServers, registerMcpCommand, registerMcpTools, } from "./mcpTools.js";
 import { registerGoCommand } from "./pipeline/goCommand.js";
@@ -359,21 +359,26 @@ export async function registerYagni(pi, deps = {}) {
         decisionsCount: briefResult?.counts?.decisions ?? 0,
         evalMode,
     });
-    // Onramp Door B (spec §5B/§7): on a FRESH workspace (empty/thin grounding
-    // corpus), the first run reads the repo, drafts the engineering-half brief + a
-    // proposed Engineering Team, and seeds decisions — instead of a bare prompt. We
-    // reuse the brief we just fetched (no double round-trip). Skipped in eval mode.
+    // ADR-0033: the Team-drafting flow is an explicit command, never a first-run
+    // ceremony. /setup-team drafts the Engineering Team + engineering brief from
+    // the repo and banks the brief as one decision on approval.
+    registerTeamSetupCommand(pi, { baseUrl, getToken: getTokenFn, fetchImpl: authedFetch });
+    // Onramp Door B (spec §5B/§7, as amended by ADR-0033): on a FRESH workspace
+    // (empty/thin grounding corpus), the first run shows a short welcome + one
+    // next-work offer, with free text first-class — instead of a bare prompt. It
+    // records nothing; Team drafting lives behind /setup-team. We reuse the brief
+    // we just fetched (no double round-trip). Skipped in eval mode.
     const runInitPassFn = deps.runInitPass ?? defaultRunInitPass;
     const getWorkspaceIdFn = deps.getWorkspaceId ?? (() => defaultGetWorkspaceId(deps.env));
     const isInitDoneFn = deps.isInitDone ?? defaultIsInitDone;
     const markInitDoneFn = deps.markInitDone ?? defaultMarkInitDone;
     const workspaceId = getWorkspaceIdFn();
-    // F2a — one-time marker (idempotency): the init pass writes only to
-    // `yagni_code_decisions`, which the context endpoint never reads back (it reads
-    // Vision + Goals), so a Vision/Goals-less workspace looks "fresh" forever and
-    // would re-seed duplicate decisions on every launch. A per-workspace marker
-    // short-circuits the pass after its first real run — regardless of brief
-    // emptiness. (Degrades to freshness-only when the workspace id is unknown.)
+    // F2a — one-time marker (idempotency): the context endpoint never reflects
+    // the welcome (it reads Vision + Goals), so a Vision/Goals-less workspace
+    // looks "fresh" forever and would re-welcome on every launch. A per-workspace
+    // marker short-circuits the pass after its first real run — regardless of
+    // brief emptiness. (Degrades to freshness-only when the workspace id is
+    // unknown.)
     const alreadyInit = !evalMode && !!workspaceId && isInitDoneFn(workspaceId);
     // F2b — fail CLOSED: a FAILED context fetch (network / non-2xx / throw) surfaces
     // as a `null` brief here (fetchContextBrief and the catch above both map failure
@@ -546,9 +551,9 @@ export { makeRecordEngineeringContextTool } from "./recordContextTool.js";
 export { makeRecordDecisionTool } from "./recordDecisionTool.js";
 export { makeSuggestNextWorkTool, defaultNextAction } from "./nextWorkTool.js";
 export { recordDecision } from "./recordDecisionTool.js";
-// Onramp Door B: the CLI init pass (fresh-workspace detection + repo intake +
-// engineering-half drafting + decision seeding + one default next action).
-export { runInitPass, isFreshWorkspace, readRepoIntake, draftEngineering, summarizeDraft, FRESH_BRIEF_MIN_CHARS, } from "./initPass.js";
+// Onramp Door B (as amended by ADR-0033): the first-run welcome (write-free,
+// free text first-class) + the explicit /setup-team drafting flow.
+export { runInitPass, runTeamSetup, registerTeamSetupCommand, isFreshWorkspace, readRepoIntake, draftEngineering, summarizeDraft, FRESH_BRIEF_MIN_CHARS, } from "./initPass.js";
 // Onramp Door B (F2a): the one-time init-pass idempotency marker.
 export { isInitDone, markInitDone, initDoneMarkerFile, _setInitDoneHomeForTest } from "./initDone.js";
 export { brandSystemPrompt, YAGNI_IDENTITY, YAGNI_IDENTITY_DRIVER, BRAND_NAME } from "./branding.js";

package/dist/extension/initPass.d.ts

@@ -1,26 +1,26 @@
 /**
- * The CLI init pass (Onramp Door B, spec §5B/§7).
+ * The CLI first-run experience (Onramp Door B, spec §5B/§7, as amended by
+ * ADR-0033: first run is a welcome, not a Team ceremony).
  *
- * On a FRESH workspace, the first `yagni` run in a repo should not drop the
- * user into a bare prompt. Instead it runs a one-time init pass:
- *   1. detect a fresh workspace (an empty/thin grounding corpus, via the existing
- *      `GET /api/yagni-code/context` brief),
- *   2. read the repo (README, AGENTS.md/CLAUDE.md, package.json scripts, ADRs),
- *   3. draft the ENGINEERING HALF of the company brief + a proposed Engineering
- *      Team, and record the salient ADRs/conventions as decisions so the corpus
- *      is non-empty for the very first `/go`,
- *   4. present the draft for approve/edit in-terminal (mirrored to the app via the
- *      recorded decisions), NEVER auto-committing the Team, and
- *   5. offer the ONE default next action (`suggest_next_work`) with escape hatches.
+ * On a FRESH workspace (an empty/thin grounding corpus, via the existing
+ * `GET /api/yagni-code/context` brief), the first interactive `yagni` run shows
+ * a short WELCOME: how to work with YAGNI in one notice, then one offer (ask
+ * @yagni what to work on next) with free text as a first-class choice.
+ * Escape/cancel land in an empty editor ready to type into, never a forced
+ * prompt. The welcome records NOTHING and reads nothing from the repo.
  *
- * Honesty rails (non-negotiable, spec §9): when a repo has no README/AGENTS/ADRs
- * the engineering half stays THIN and SAYS SO — nothing is fabricated, and no
- * decision is seeded from thin air. The proposed Team is only ever a DRAFT; it is
- * never created/committed automatically.
+ * The Team-drafting flow (repo intake -> engineering-half draft -> approve/edit
+ * -> bank the brief as ONE decision) lives behind the explicit `/setup-team`
+ * command ({@link registerTeamSetupCommand}) so onboarding can invoke it
+ * deliberately. Honesty rails are unchanged (spec §9, F2/F13): approval-gated
+ * writes, honest-when-thin (nothing fabricated), the Team is only ever a DRAFT
+ * and never created automatically, and the repo intake reads only universal
+ * signals (README, AGENTS.md/CLAUDE.md, package.json scripts) so it behaves
+ * the same on any customer repo.
  *
  * No new backend transport: the only writes are through the existing token-scoped
  * `record_decision` endpoint (reused via {@link recordDecision}). Every seam is
- * injectable so the whole pass is unit-testable without a network or a filesystem.
+ * injectable so both flows are unit-testable without a network or a filesystem.
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { fetchContextBrief as defaultFetchContextBrief, type ContextBrief } from "./config.js";
@@ -39,16 +39,12 @@ export declare const FRESH_BRIEF_MIN_CHARS = 40;
  * populated and the init pass must be skipped.
  */
 export declare function isFreshWorkspace(brief: ContextBrief | null | undefined): boolean;
-/** A single architecture-decision record found in the repo. */
-export interface RepoAdr {
-    /** Repo-relative path, e.g. `docs/adr/0001-use-fly.md`. */
-    path: string;
-    /** The record's title (its first heading, or the filename when headingless). */
-    title: string;
-    /** A short first-paragraph summary, when present. */
-    summary?: string;
-}
-/** What the repo intake could find. All fields are best-effort / optional. */
+/**
+ * What the repo intake could find. All fields are best-effort / optional, and
+ * every signal is a UNIVERSAL repo convention (README, agents file, package
+ * scripts) — never a house-specific layout like docs/adr, so the intake
+ * behaves the same on any customer repo.
+ */
 export interface RepoIntake {
     /** README body (capped), when present. */
     readme?: string;
@@ -56,8 +52,6 @@ export interface RepoIntake {
     agents?: string;
     /** package.json `scripts` map (empty when absent/unparseable). */
     packageScripts: Record<string, string>;
-    /** Architecture decision records found under docs/adr (etc.). */
-    adrs: RepoAdr[];
     /** The literal test command (package.json `scripts.test`), when present. */
     testCommand?: string;
     /** The literal build command (package.json `scripts.build`), when present. */
@@ -66,7 +60,6 @@ export interface RepoIntake {
 /** Injectable filesystem seam so repo intake is unit-testable without disk. */
 export interface RepoIntakeFs {
     readFile(p: string): Promise<string>;
-    readdir(p: string): Promise<string[]>;
 }
 /**
  * Read the repo at `cwd` for the signals that seed the engineering half of the
@@ -81,13 +74,12 @@ export interface DraftTeam {
     playbookRules: string[];
     testCommand?: string;
     buildCommand?: string;
-    riskAreas: string[];
 }
 /** The drafted engineering half: the brief, seeded decisions, and a Team draft. */
 export interface EngineeringDraft {
     /** The engineering-half brief text (honest-when-thin). */
     brief: string;
-    /** True when the repo had no README/AGENTS/ADRs — the brief says so, nothing is fabricated. */
+    /** True when the repo had no README/AGENTS — the brief says so, nothing is fabricated. */
     thin: boolean;
     /** Decisions to seed into the corpus. EMPTY when thin (no fabrication). */
     decisions: RecordDecisionParams[];
@@ -96,10 +88,10 @@ export interface EngineeringDraft {
 }
 /**
  * Draft the engineering half of the brief from repo intake. PURE. Honest-when-thin:
- * with no README/AGENTS/ADRs the brief says so and NO decision is seeded.
+ * with no README/AGENTS the brief says so and NO decision is seeded.
  */
 export declare function draftEngineering(intake: RepoIntake): EngineeringDraft;
-/** Injectable dependencies for {@link runInitPass}. */
+/** Injectable dependencies for {@link runInitPass} (the first-run welcome). */
 export interface RunInitPassDeps {
     baseUrl: string;
     getToken: () => string | undefined;
@@ -111,23 +103,34 @@ export interface RunInitPassDeps {
      */
     brief?: ContextBrief | null;
     fetchContextBrief?: typeof defaultFetchContextBrief;
-    readRepoIntake?: (cwd: string) => Promise<RepoIntake>;
-    recordDecision?: typeof defaultRecordDecision;
 }
-/** The outcome of an init-pass attempt. */
+/** The outcome of a first-run welcome attempt. The welcome never writes. */
 export type InitPassOutcome = {
     ran: false;
     reason: "not_fresh" | "non_interactive";
+} | {
+    ran: true;
+    /** What the user picked; `free_text` covers the typing option AND escape/cancel. */
+    chosenAction: NextActionOption["id"] | "free_text";
+};
+/** Injectable dependencies for {@link runTeamSetup} (the `/setup-team` flow). */
+export interface RunTeamSetupDeps {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+    readRepoIntake?: (cwd: string) => Promise<RepoIntake>;
+    recordDecision?: typeof defaultRecordDecision;
+}
+/** The outcome of a `/setup-team` run. */
+export type TeamSetupOutcome = {
+    ran: false;
+    reason: "non_interactive";
 } | {
     ran: true;
     thin: boolean;
     decisionsRecorded: number;
-    /** The Team was drafted for the user. */
-    teamDrafted: true;
     /** The Team is NEVER created/committed automatically. Always false. */
     teamCommitted: false;
-    /** Which next action the user picked (undefined in headless mode). */
-    chosenAction?: NextActionOption["id"];
 };
 /**
  * Compact one-screen PREVIEW of the draft for the approve/edit dialog.
@@ -141,12 +144,27 @@ export type InitPassOutcome = {
  */
 export declare function summarizeDraft(draft: EngineeringDraft): string;
 /**
- * Run the init pass. Guards on fresh-workspace detection (defensive — the caller
- * also guards), reads the repo, drafts the engineering half, presents it for
- * approve/edit, and ONLY THEN seeds the corpus (approval-gated: an approve banks
- * the drafted decisions, an edit banks the correction, a decline writes nothing),
- * before offering the one default next action. Fully fail-soft: a UI or network
- * hiccup never throws (it must never break session start).
+ * Run the first-run welcome (ADR-0033). Guards on fresh-workspace detection
+ * (defensive — the caller also guards), shows a short how-to-work-with-YAGNI
+ * notice, and offers ONE default next action (ask @yagni what to work on next)
+ * with free text as a first-class choice. Picking "Just start typing",
+ * pressing escape, or cancelling all leave the editor untouched so the user
+ * can type whatever they want to start on. Records NOTHING, reads nothing from
+ * the repo, and is fully fail-soft (it must never break session start).
  */
 export declare function runInitPass(pi: ExtensionAPI, ctx: ExtensionContext, deps: RunInitPassDeps): Promise<InitPassOutcome>;
+/**
+ * Run the `/setup-team` flow: read the repo's universal signals, draft the
+ * engineering half + a proposed Team, present it for approve/edit, and ONLY
+ * THEN bank the brief as one decision (approval-gated: an approve banks the
+ * draft, an edit banks the correction, a decline writes nothing). Fully
+ * fail-soft; the Team itself is never created automatically.
+ */
+export declare function runTeamSetup(pi: ExtensionAPI, ctx: ExtensionContext, deps: RunTeamSetupDeps): Promise<TeamSetupOutcome>;
+/**
+ * Register `/setup-team`: the explicit, approval-gated flow that drafts the
+ * Engineering Team + engineering brief from the repo. Deliberately NOT part of
+ * first-run (ADR-0033) — onboarding invokes it when the workspace is ready.
+ */
+export declare function registerTeamSetupCommand(pi: ExtensionAPI, opts: RunTeamSetupDeps): void;
 //# sourceMappingURL=initPass.d.ts.map

package/dist/extension/initPass.js

@@ -1,28 +1,28 @@
 /**
- * The CLI init pass (Onramp Door B, spec §5B/§7).
+ * The CLI first-run experience (Onramp Door B, spec §5B/§7, as amended by
+ * ADR-0033: first run is a welcome, not a Team ceremony).
  *
- * On a FRESH workspace, the first `yagni` run in a repo should not drop the
- * user into a bare prompt. Instead it runs a one-time init pass:
- *   1. detect a fresh workspace (an empty/thin grounding corpus, via the existing
- *      `GET /api/yagni-code/context` brief),
- *   2. read the repo (README, AGENTS.md/CLAUDE.md, package.json scripts, ADRs),
- *   3. draft the ENGINEERING HALF of the company brief + a proposed Engineering
- *      Team, and record the salient ADRs/conventions as decisions so the corpus
- *      is non-empty for the very first `/go`,
- *   4. present the draft for approve/edit in-terminal (mirrored to the app via the
- *      recorded decisions), NEVER auto-committing the Team, and
- *   5. offer the ONE default next action (`suggest_next_work`) with escape hatches.
+ * On a FRESH workspace (an empty/thin grounding corpus, via the existing
+ * `GET /api/yagni-code/context` brief), the first interactive `yagni` run shows
+ * a short WELCOME: how to work with YAGNI in one notice, then one offer (ask
+ * @yagni what to work on next) with free text as a first-class choice.
+ * Escape/cancel land in an empty editor ready to type into, never a forced
+ * prompt. The welcome records NOTHING and reads nothing from the repo.
  *
- * Honesty rails (non-negotiable, spec §9): when a repo has no README/AGENTS/ADRs
- * the engineering half stays THIN and SAYS SO — nothing is fabricated, and no
- * decision is seeded from thin air. The proposed Team is only ever a DRAFT; it is
- * never created/committed automatically.
+ * The Team-drafting flow (repo intake -> engineering-half draft -> approve/edit
+ * -> bank the brief as ONE decision) lives behind the explicit `/setup-team`
+ * command ({@link registerTeamSetupCommand}) so onboarding can invoke it
+ * deliberately. Honesty rails are unchanged (spec §9, F2/F13): approval-gated
+ * writes, honest-when-thin (nothing fabricated), the Team is only ever a DRAFT
+ * and never created automatically, and the repo intake reads only universal
+ * signals (README, AGENTS.md/CLAUDE.md, package.json scripts) so it behaves
+ * the same on any customer repo.
  *
  * No new backend transport: the only writes are through the existing token-scoped
  * `record_decision` endpoint (reused via {@link recordDecision}). Every seam is
- * injectable so the whole pass is unit-testable without a network or a filesystem.
+ * injectable so both flows are unit-testable without a network or a filesystem.
  */
-import { readFile as fsReadFile, readdir as fsReaddir } from "node:fs/promises";
+import { readFile as fsReadFile } from "node:fs/promises";
 import path from "node:path";
 import { fetchContextBrief as defaultFetchContextBrief, } from "./config.js";
 import { defaultNextAction } from "./nextWorkTool.js";
@@ -59,23 +59,13 @@ const nodeIntakeFs = {
             return "";
         }
     },
-    async readdir(p) {
-        try {
-            return await fsReaddir(p);
-        }
-        catch {
-            return [];
-        }
-    },
 };
 /** Candidate filenames, tried in order; the first that reads non-empty wins. */
 const README_CANDIDATES = ["README.md", "README", "readme.md", "README.markdown"];
 const AGENTS_CANDIDATES = ["AGENTS.md", "CLAUDE.md"];
-const ADR_DIRS = ["docs/adr", "docs/adrs", "docs/decisions"];
 /** Cap the amount of prose we lift so a large README never bloats the brief. */
 const MAX_DOC_CHARS = 4000;
 const MAX_SUMMARY_CHARS = 280;
-const MAX_ADRS = 25;
 async function firstNonEmpty(fs, cwd, names) {
     for (const name of names) {
         const body = (await fs.readFile(path.join(cwd, name))).trim();
@@ -104,59 +94,38 @@ function parseScripts(raw) {
         return {};
     }
 }
-/** The first `# heading` (or the filename) as a title; first paragraph as summary. */
-function extractAdr(relPath, content) {
-    const heading = content.match(/^#{1,3}\s+(.+)$/m);
-    const title = heading?.[1]?.trim() || path.basename(relPath).replace(/\.[^.]+$/, "");
-    // First non-heading, non-empty paragraph.
-    const paragraphs = content
-        .split(/\n\s*\n/)
-        .map((p) => p.trim())
-        .filter((p) => p && !p.startsWith("#"));
-    const summary = paragraphs[0]?.replace(/\s+/g, " ").slice(0, MAX_SUMMARY_CHARS);
-    return { path: relPath, title, summary: summary || undefined };
-}
-async function readAdrs(fs, cwd) {
-    const adrs = [];
-    for (const dir of ADR_DIRS) {
-        const entries = await fs.readdir(path.join(cwd, dir));
-        for (const entry of entries.filter((e) => /\.m(d|arkdown)$/i.test(e)).sort()) {
-            if (adrs.length >= MAX_ADRS)
-                return adrs;
-            const rel = `${dir}/${entry}`;
-            const content = await fs.readFile(path.join(cwd, rel));
-            if (content.trim())
-                adrs.push(extractAdr(rel, content));
-        }
-    }
-    return adrs;
-}
 /**
  * Read the repo at `cwd` for the signals that seed the engineering half of the
  * brief. Every read is best-effort; a missing file simply drops that signal.
  */
 export async function readRepoIntake(cwd, fs = nodeIntakeFs) {
-    const [readme, agents, pkgRaw, adrs] = await Promise.all([
+    const [readme, agents, pkgRaw] = await Promise.all([
         firstNonEmpty(fs, cwd, README_CANDIDATES),
         firstNonEmpty(fs, cwd, AGENTS_CANDIDATES),
         fs.readFile(path.join(cwd, "package.json")),
-        readAdrs(fs, cwd),
     ]);
     const packageScripts = parseScripts(pkgRaw);
     return {
         readme,
         agents,
         packageScripts,
-        adrs,
         testCommand: packageScripts.test || undefined,
         buildCommand: packageScripts.build || undefined,
     };
 }
-const THIN_BRIEF = "I couldn't find a README, AGENTS.md/CLAUDE.md, or ADRs in this repo, so I don't " +
+const THIN_BRIEF = "I couldn't find a README or AGENTS.md/CLAUDE.md in this repo, so I don't " +
     "know much about how you build yet. Tell me in a line what this repo is and how " +
     "you build it, and I'll fill in the engineering brief.";
-const TEAM_MISSION = "Owns how we build: conventions, reviews, test/build, and risk areas.";
-/** The README's first real paragraph (heading-stripped), capped. */
+const TEAM_MISSION = "Owns how we build: conventions, reviews, and test/build.";
+/** Cap `text` at `max` chars, cutting back to the last word boundary with an ellipsis. */
+function truncateAtWord(text, max) {
+    if (text.length <= max)
+        return text;
+    const cut = text.slice(0, max);
+    const lastSpace = cut.lastIndexOf(" ");
+    return `${(lastSpace > 0 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}
+/** The README's first real paragraph (heading-stripped), capped at a word boundary. */
 function firstParagraph(readme) {
     if (!readme)
         return undefined;
@@ -164,14 +133,16 @@ function firstParagraph(readme) {
         .split(/\n\s*\n/)
         .map((p) => p.trim())
         .find((p) => p && !p.startsWith("#") && !/^[!\[]/.test(p));
-    return para?.replace(/\s+/g, " ").slice(0, MAX_SUMMARY_CHARS);
+    if (!para)
+        return undefined;
+    return truncateAtWord(para.replace(/\s+/g, " "), MAX_SUMMARY_CHARS);
 }
 /**
  * Draft the engineering half of the brief from repo intake. PURE. Honest-when-thin:
- * with no README/AGENTS/ADRs the brief says so and NO decision is seeded.
+ * with no README/AGENTS the brief says so and NO decision is seeded.
  */
 export function draftEngineering(intake) {
-    const hasSubstance = Boolean(intake.readme || intake.agents || intake.adrs.length);
+    const hasSubstance = Boolean(intake.readme || intake.agents);
     const thin = !hasSubstance;
     const team = {
         name: "Engineering",
@@ -180,9 +151,6 @@ export function draftEngineering(intake) {
         playbookRules: [],
         testCommand: intake.testCommand,
         buildCommand: intake.buildCommand,
-        riskAreas: intake.adrs
-            .filter((a) => /risk|security|migration|billing|auth/i.test(a.title))
-            .map((a) => a.title),
     };
     if (intake.testCommand)
         team.playbookRules.push(`Run \`${intake.testCommand}\` before handing off a change.`);
@@ -197,8 +165,6 @@ export function draftEngineering(intake) {
         team.responsibilities.push("Uphold the conventions documented in AGENTS.md/CLAUDE.md.");
     if (intake.testCommand || intake.buildCommand)
         team.responsibilities.push("Keep the build and tests green.");
-    if (intake.adrs.length)
-        team.responsibilities.push("Steward the architecture decisions in docs/adr.");
     if (team.responsibilities.length === 0)
         team.responsibilities.push("Own how this team builds software.");
     const lines = ["How this team builds software (drafted from repo intake — a draft, editable):"];
@@ -211,23 +177,17 @@ export function draftEngineering(intake) {
         lines.push(`- Tests: \`${intake.testCommand}\``);
     if (intake.buildCommand)
         lines.push(`- Build: \`${intake.buildCommand}\``);
-    if (intake.adrs.length)
-        lines.push(`- Decisions on record: ${intake.adrs.map((a) => a.title).join("; ")}`);
     const brief = lines.join("\n");
-    // Seed the corpus so the very first /go has real ground to cite. The brief
-    // itself is banked as one grounding entry, then each ADR/convention as a
-    // decision. All are DRAFTS (editable), never treated as immutable fact.
+    // Seed the corpus with ONE entry so the very first /go has real ground to
+    // cite: the drafted brief itself. Repo docs stay in the repo where the agent
+    // can read them whole; regex-lifted fragments are never banked as decisions.
+    // The brief is a DRAFT (editable), never treated as immutable fact.
     const decisions = [
         {
             question: "How does this team build software?",
             decision: brief,
-            rationale: "Drafted from repo intake (README/AGENTS/ADRs) during the first YAGNI Code run; a draft, editable.",
+            rationale: "Drafted from repo intake (README/AGENTS) during the first YAGNI Code run; a draft, editable.",
         },
-        ...intake.adrs.map((adr) => ({
-            question: `What does "${adr.title}" decide?`,
-            decision: adr.summary || adr.title,
-            rationale: `Recorded from ${adr.path} during repo intake.`,
-        })),
     ];
     return { brief, thin: false, decisions, team };
 }
@@ -250,27 +210,37 @@ export function summarizeDraft(draft) {
         parts.push("", "(Engineering context is thin — nothing to record yet; I never fabricate one.)");
     }
     else if (draft.decisions.length > 0) {
-        parts.push("", `On approval I'll record ${draft.decisions.length} decision(s) into your grounding corpus.`);
+        parts.push("", "On approval I'll save this brief into your grounding corpus. Nothing else is recorded.");
     }
     parts.push("", "This Team is a draft — it is never created automatically. You can edit it first.");
     return parts.join("\n");
 }
+/** A permissive notify wrapper: a notice must never disrupt a flow. */
+function safeNotify(ui) {
+    return (message, type) => {
+        try {
+            ui?.notify?.(message, type);
+        }
+        catch {
+            /* swallowed */
+        }
+    };
+}
+/** The one-notice welcome shown on the very first interactive run in a repo. */
+const WELCOME_NOTICE = "First run in this repo. Just type to start working. Ask me about your company " +
+    "context (tickets, docs, decisions), or run /go <ticket> for a ticket-to-PR run.";
+/** The free-text choice: an untouched editor, ready for whatever they want to build. */
+const FREE_TEXT_LABEL = "Just start typing";
 /**
- * Run the init pass. Guards on fresh-workspace detection (defensive — the caller
- * also guards), reads the repo, drafts the engineering half, presents it for
- * approve/edit, and ONLY THEN seeds the corpus (approval-gated: an approve banks
- * the drafted decisions, an edit banks the correction, a decline writes nothing),
- * before offering the one default next action. Fully fail-soft: a UI or network
- * hiccup never throws (it must never break session start).
+ * Run the first-run welcome (ADR-0033). Guards on fresh-workspace detection
+ * (defensive — the caller also guards), shows a short how-to-work-with-YAGNI
+ * notice, and offers ONE default next action (ask @yagni what to work on next)
+ * with free text as a first-class choice. Picking "Just start typing",
+ * pressing escape, or cancelling all leave the editor untouched so the user
+ * can type whatever they want to start on. Records NOTHING, reads nothing from
+ * the repo, and is fully fail-soft (it must never break session start).
  */
 export async function runInitPass(pi, ctx, deps) {
-    const recordDecisionFn = deps.recordDecision ?? defaultRecordDecision;
-    const readIntake = deps.readRepoIntake ?? ((cwd) => readRepoIntake(cwd));
-    const decisionOpts = {
-        baseUrl: deps.baseUrl,
-        getToken: deps.getToken,
-        fetchImpl: deps.fetchImpl,
-    };
     // 1. Fresh-workspace guard (skip when already grounded).
     const brief = deps.brief !== undefined
         ? deps.brief
@@ -281,45 +251,78 @@ export async function runInitPass(pi, ctx, deps) {
         }).catch(() => null);
     if (!isFreshWorkspace(brief))
         return { ran: false, reason: "not_fresh" };
+    // In non-interactive / print (`-p`) / no-UI mode there is no one to welcome;
+    // skip WITHOUT marking init-done so the first interactive run still gets it.
     const ui = (ctx.hasUI ? ctx.ui : undefined);
-    // 1b. Approval-gated writes (spec §5B/§9 — captured-judgment beat): the init
-    // pass records decisions into the corpus, but a decision only earns its place
-    // when a human can see and approve/edit the draft. In non-interactive / print
-    // (`-p`) / no-UI mode there is no one to approve, so we NEVER write — we skip
-    // the pass entirely (returning ran:false so the caller does NOT mark the
-    // workspace init-done, leaving the seed for the first interactive run).
     if (!ui)
         return { ran: false, reason: "non_interactive" };
-    const notify = (message, type) => {
-        try {
-            ui?.notify?.(message, type);
-        }
-        catch {
-            /* a notice must never disrupt the pass */
+    const notify = safeNotify(ui);
+    notify(WELCOME_NOTICE, "info");
+    // 2. Offer the ONE default next action (spec §7.3: defaults over choices),
+    //    with free text as a first-class door. Everything here is best-effort:
+    //    whatever happens, the user ends at a prompt they can just type into.
+    let chosenAction = "free_text";
+    try {
+        const next = defaultNextAction();
+        const review = next.escapeHatches.find((h) => h.id === "review");
+        if (typeof ui.select === "function") {
+            const options = [next.primary, ...(review ? [review] : [])];
+            const labels = [next.primary.label, FREE_TEXT_LABEL, ...(review ? [review.label] : [])];
+            const picked = await ui.select("What next?", labels);
+            const chosen = options.find((o) => o.label === picked);
+            // "Just start typing", escape, and cancel all leave the editor alone —
+            // a first run must never force a prompt on the user.
+            if (chosen) {
+                chosenAction = chosen.id;
+                ui.setEditorText?.(chosen.prompt);
+            }
         }
+    }
+    catch {
+        /* the offer is best-effort; free text always works */
+    }
+    return { ran: true, chosenAction };
+}
+/**
+ * Run the `/setup-team` flow: read the repo's universal signals, draft the
+ * engineering half + a proposed Team, present it for approve/edit, and ONLY
+ * THEN bank the brief as one decision (approval-gated: an approve banks the
+ * draft, an edit banks the correction, a decline writes nothing). Fully
+ * fail-soft; the Team itself is never created automatically.
+ */
+export async function runTeamSetup(pi, ctx, deps) {
+    const recordDecisionFn = deps.recordDecision ?? defaultRecordDecision;
+    const readIntake = deps.readRepoIntake ?? ((cwd) => readRepoIntake(cwd));
+    const decisionOpts = {
+        baseUrl: deps.baseUrl,
+        getToken: deps.getToken,
+        fetchImpl: deps.fetchImpl,
     };
-    notify("YAGNI Code — first run in this repo. Reading it to seed your engineering brief…", "info");
-    // 2. Read the repo + draft the engineering half.
+    // Approval-gated writes (spec §5B/§9 — captured-judgment beat): a decision
+    // only earns its place when a human can see and approve/edit the draft. With
+    // no UI there is no one to approve, so we NEVER write.
+    const ui = (ctx.hasUI ? ctx.ui : undefined);
+    if (!ui)
+        return { ran: false, reason: "non_interactive" };
+    const notify = safeNotify(ui);
+    notify("Reading the repo to draft your Engineering Team…", "info");
+    // 1. Read the repo + draft the engineering half.
     let intake;
     try {
-        intake = await readIntake(ctx.cwd);
+        intake = await readIntake(ctx.cwd ?? process.cwd());
     }
     catch {
-        intake = { packageScripts: {}, adrs: [] };
+        intake = { packageScripts: {} };
     }
     const draft = draftEngineering(intake);
-    // 3. Present the draft for approve/edit BEFORE any durable write (spec §5B/§9,
-    //    F2/F13 — approval-gated writes). A decision earns its place in the corpus
-    //    only once the human has APPROVED the draft or CORRECTED it; nothing is
-    //    written before the dialog. The Team itself is never auto-committed. In a
-    //    UI without a `confirm` capability there is no way to obtain approval, so
-    //    (consistent with the no-UI guard above) we write nothing.
+    // 2. Present the draft for approve/edit BEFORE any durable write (F2/F13).
+    //    In a UI without a `confirm` capability there is no way to obtain
+    //    approval, so (consistent with the no-UI guard above) we write nothing.
     let decisionsRecorded = 0;
-    let chosenAction;
     try {
         let approved = false;
         let correctedBrief;
-        if (ui && typeof ui.confirm === "function") {
+        if (typeof ui.confirm === "function") {
             approved = await ui.confirm("Your draft Engineering Team", summarizeDraft(draft));
             if (!approved && typeof ui.editor === "function") {
                 const edited = await ui.editor("Edit the engineering brief", draft.brief);
@@ -328,11 +331,11 @@ export async function runInitPass(pi, ctx, deps) {
                 }
             }
         }
-        // 4. Approval-gated corpus writes. APPROVE → bank the drafted decisions.
-        //    REJECT-then-correct → bank ONLY the correction (the rejected auto-draft
-        //    is never written). REJECT without an edit (or no approval UI) → write
-        //    NOTHING. Best-effort throughout: a failed write is swallowed and the
-        //    recorded count stays honest (F13).
+        // 3. Approval-gated corpus writes. APPROVE → bank the drafted brief
+        //    decision. REJECT-then-correct → bank ONLY the correction (the
+        //    rejected auto-draft is never written). REJECT without an edit (or no
+        //    approval UI) → write NOTHING. Best-effort throughout: a failed write
+        //    is swallowed and the recorded count stays honest (F13).
         if (approved) {
             for (const decision of draft.decisions) {
                 try {
@@ -352,7 +355,7 @@ export async function runInitPass(pi, ctx, deps) {
                 const result = await recordDecisionFn(decisionOpts, {
                     question: "How does this team build software?",
                     decision: correctedBrief,
-                    rationale: "The user edited the drafted engineering brief during the init pass.",
+                    rationale: "The user edited the drafted engineering brief during team setup.",
                 }, ctx.signal);
                 if (!result.spooled)
                     decisionsRecorded += 1;
@@ -364,31 +367,28 @@ export async function runInitPass(pi, ctx, deps) {
         // Report the ACTUAL recorded count once the write has run (never the
         // intended count) so the receipt is honest even on a partial/failed write.
         if (decisionsRecorded > 0) {
-            notify(`Recorded ${decisionsRecorded} decision(s) into your grounding corpus.`, "info");
-        }
-        // 5. Offer the ONE default next action (not a four-option chooser).
-        const next = defaultNextAction();
-        if (ui && typeof ui.select === "function") {
-            const labels = [next.primary.label, ...next.escapeHatches.map((h) => h.label)];
-            const picked = await ui.select("What next?", labels);
-            const chosen = [next.primary, ...next.escapeHatches].find((o) => o.label === picked) ?? next.primary;
-            chosenAction = chosen.id;
-            ui.setEditorText?.(chosen.prompt);
+            notify("Saved your engineering brief into the grounding corpus.", "info");
         }
-        else {
-            notify(`Next: ${next.primary.prompt}`, "info");
+        else if (!draft.thin) {
+            notify("Nothing recorded.", "info");
         }
     }
     catch {
-        /* the presentation is best-effort; the corpus is already seeded */
+        /* the presentation is best-effort */
     }
-    return {
-        ran: true,
-        thin: draft.thin,
-        decisionsRecorded,
-        teamDrafted: true,
-        teamCommitted: false,
-        chosenAction,
-    };
+    return { ran: true, thin: draft.thin, decisionsRecorded, teamCommitted: false };
+}
+/**
+ * Register `/setup-team`: the explicit, approval-gated flow that drafts the
+ * Engineering Team + engineering brief from the repo. Deliberately NOT part of
+ * first-run (ADR-0033) — onboarding invokes it when the workspace is ready.
+ */
+export function registerTeamSetupCommand(pi, opts) {
+    pi.registerCommand("setup-team", {
+        description: "Draft an Engineering Team + engineering brief from this repo; nothing is saved without your approval.",
+        handler: async (_args, ctx) => {
+            await runTeamSetup(pi, ctx, opts);
+        },
+    });
 }
 //# sourceMappingURL=initPass.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "0.1.0-staging.1019.1",
+  "version": "0.1.0-staging.1020.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -38,5 +38,5 @@
     "@earendil-works/pi-tui": "0.83.0",
     "typebox": "^1.1.38"
   },
-  "yagniSourceSha": "03dc13fce991758459702c7178a5f4cfa5d110b7"
+  "yagniSourceSha": "db184c4a3d15bc4b5e140a5337f34be7dadbb943"
 }