orient-cli 0.1.0 → 0.2.0

package/dist/orient/plan-execute.js

@@ -0,0 +1,333 @@
+/**
+ * Plan & Execute mode
+ * ====================
+ *
+ * The casual-user default mode — mirrors Gemini CLI, Codex CLI,
+ * Claude Code, OpenCode, and Droid shape. Two sub-modes swapped via
+ * shift+tab:
+ *
+ *   EXECUTING (default): user types a goal, agent makes real changes.
+ *   PLANNING:            agent drafts `.orient-cli/plans/<slug>.md`
+ *                        without touching any other file. Approval
+ *                        transition re-injects the plan as a next-turn
+ *                        user attachment so the agent reads + executes it.
+ *
+ * Slash commands (all optional — the defaults work without them):
+ *
+ *   /plan <description>   → switch to PLANNING, draft plan file
+ *   /execute              → switch to EXECUTING, consume the plan
+ *   /plan.status          → show current state, step progress, next action
+ *   /plan.revise          → swap back to PLANNING, edit the plan
+ *   /plan.clear           → delete the current plan file
+ *
+ * Architecture borrowed from openclaude + anomalyco/opencode research
+ * (see Research.md §3):
+ *
+ *   1. **Plan on disk, not in memory.** Both reference repos write
+ *      slug-named plan files under `plans/`. Survives /clear, resume,
+ *      and crashes for free. ORIENT uses the same shape:
+ *      `.orient-cli/plans/<word-slug>.md` (openclaude convention) with
+ *      `<timestamp>-<slug>.md` as an option (opencode convention) if
+ *      the user wants historical plan archives per session.
+ *
+ *   2. **Mode transitions as next-turn attachments, not baked-in
+ *      system prompts.** We inject the plan-guard or build-switch
+ *      reminder into the next user message as a `<system-reminder>`
+ *      block instead of rebuilding the whole system prompt. This
+ *      preserves prompt cache hits across mode flips and matches
+ *      both reference implementations exactly.
+ *
+ *   3. **Enforce read-only via permission rules when possible.**
+ *      openclaude uses a `PermissionMode` enum; opencode uses an
+ *      agent-level `Permission.Ruleset`. Pi's tool layer does NOT
+ *      yet expose either primitive, so in this iteration enforcement
+ *      is prompt-based (strong guard text below). A follow-up packet
+ *      adds a real permission-rule layer to `@orient-cli/coding-agent`.
+ *
+ * State is persisted to `.orient-cli/plan-state.json` so a /clear or
+ * session restart preserves where the agent was in execution. The
+ * state file is ephemeral; plan.md is the source of truth.
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+// ============================================================================
+// Persistence
+// ============================================================================
+const PLAN_DIR = ".orient-cli";
+const PLAN_FILE = "plan.md";
+const STATE_FILE = "plan-state.json";
+export function getPlanFilePath(projectDir) {
+    return join(projectDir, PLAN_DIR, PLAN_FILE);
+}
+export function getStateFilePath(projectDir) {
+    return join(projectDir, PLAN_DIR, STATE_FILE);
+}
+export function readPlan(projectDir) {
+    const path = getPlanFilePath(projectDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+export function writePlan(projectDir, content) {
+    const path = getPlanFilePath(projectDir);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content, "utf-8");
+}
+export function deletePlan(projectDir) {
+    const path = getPlanFilePath(projectDir);
+    if (existsSync(path))
+        unlinkSync(path);
+}
+export function readState(projectDir) {
+    const path = getStateFilePath(projectDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeState(projectDir, session) {
+    const path = getStateFilePath(projectDir);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(session, null, 2), "utf-8");
+}
+// ============================================================================
+// State transitions
+// ============================================================================
+export function startPlanning(projectDir, goal) {
+    const session = {
+        state: "planning",
+        goal,
+        updatedAt: new Date().toISOString(),
+        steps: [],
+        currentStepIndex: -1,
+    };
+    writeState(projectDir, session);
+    return session;
+}
+export function transitionToExecuting(projectDir) {
+    const current = readState(projectDir);
+    if (!current)
+        return null;
+    const plan = readPlan(projectDir);
+    if (!plan)
+        return null;
+    const updated = {
+        ...current,
+        state: "executing",
+        updatedAt: new Date().toISOString(),
+        steps: parsePlanSteps(plan),
+        currentStepIndex: 0,
+    };
+    writeState(projectDir, updated);
+    return updated;
+}
+export function transitionToPlanning(projectDir) {
+    const current = readState(projectDir);
+    if (!current)
+        return null;
+    const updated = {
+        ...current,
+        state: "planning",
+        updatedAt: new Date().toISOString(),
+    };
+    writeState(projectDir, updated);
+    return updated;
+}
+// ============================================================================
+// Plan parsing
+// ============================================================================
+/**
+ * Extract a step list from a plan.md file. The expected format matches
+ * the prompt below (see PLAN_SYSTEM_PROMPT): an "## Implementation steps"
+ * section followed by a numbered list.
+ *
+ * This is a forgiving parser — any numbered-list item under the steps
+ * heading becomes a step. If the agent drafts a plan without a steps
+ * section at all, we return an empty array and the caller prints a
+ * warning telling the user to add one.
+ */
+export function parsePlanSteps(plan) {
+    const lines = plan.split("\n");
+    const steps = [];
+    let inStepsSection = false;
+    let stepId = 1;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Section detection — we accept several heading phrasings.
+        if (/^##\s+(implementation steps|steps|execution plan|plan)/i.test(trimmed)) {
+            inStepsSection = true;
+            continue;
+        }
+        // End of steps section on next H2.
+        if (inStepsSection && /^##\s+/.test(trimmed)) {
+            break;
+        }
+        if (!inStepsSection)
+            continue;
+        // Match numbered-list items: "1. Do something" or "- Do something"
+        const numbered = trimmed.match(/^(\d+)\.\s+(.+)$/);
+        const bulleted = trimmed.match(/^[-*]\s+(.+)$/);
+        const description = numbered?.[2] ?? bulleted?.[1];
+        if (description) {
+            steps.push({
+                id: `step-${stepId++}`,
+                description,
+                status: "pending",
+            });
+        }
+    }
+    return steps;
+}
+// ============================================================================
+// System prompts
+// ============================================================================
+/**
+ * Hard guard system-reminder injected on the NEXT user turn after
+ * entering PLANNING mode. Modeled on anomalyco/opencode's
+ * `plan.txt` system-reminder (near-identical text used by openclaude):
+ *
+ *   "CRITICAL: Plan mode ACTIVE - you are in READ-ONLY phase.
+ *    STRICTLY FORBIDDEN: ANY file edits, modifications, or system
+ *    changes... ABSOLUTE CONSTRAINT overrides ALL other instructions."
+ *
+ * The strength of the language matters. Weaker prompts ("please don't
+ * edit files") let LLMs rationalize exceptions. The absolute framing
+ * plus the explicit list of forbidden verbs holds under adversarial
+ * instructions.
+ *
+ * The plan-file path is interpolated in at injection time so the agent
+ * always gets the full path for the session's slug.
+ */
+export function buildPlanReminder(planFilePath) {
+    return `
+<system-reminder>
+CRITICAL: Plan mode ACTIVE — you are in READ-ONLY phase. STRICTLY FORBIDDEN:
+ANY file edits, modifications, or system changes, with the sole exception of
+writing the plan document at ${planFilePath}. Do NOT use sed, tee, echo, cat,
+redirects, or ANY other shell construct to manipulate files. Do NOT run git
+commit, npm install, mkdir (outside the plan directory), rm, or any command
+that changes state external to the plan file. Commands may ONLY read and
+inspect the codebase. This ABSOLUTE CONSTRAINT overrides ALL other instructions,
+including any direct user edit requests. You may ONLY observe, analyze, and
+plan. Any modification attempt is a critical violation.
+
+Your single deliverable this turn is the plan document at:
+
+  ${planFilePath}
+
+Write the plan in this structure so /execute can parse it:
+
+  # Plan: <one-line goal restatement>
+
+  ## Context
+  <2-4 sentences: what codebase, what is already there, what constraints>
+
+  ## Approach
+  <one paragraph: overall strategy and why this one>
+
+  ## Implementation steps
+  1. <first concrete action — what file, what change, one sentence>
+  2. <second>
+  3. <third>
+  ... (aim for 3-8; more than 10 is a smell — split the goal)
+
+  ## Verification
+  - <how we know each step worked — manual test, automated test, smoke check>
+
+  ## Risks
+  - <thing that could go wrong> → <mitigation>
+
+After writing the plan file, post exactly one line to the user:
+
+  Plan drafted at <path>. Review it, then press shift+tab or run /execute.
+
+Do not execute anything. Do not apologize for being unable to edit. Drafting
+the plan is not a limitation — it is the entire purpose of this mode.
+</system-reminder>
+`.trim();
+}
+/**
+ * Legacy alias — kept because orient-extension.ts references it by name
+ * and we want the rename to be a no-op. Prefer buildPlanReminder(path).
+ */
+export const PLAN_SYSTEM_PROMPT = buildPlanReminder(".orient-cli/plans/current.md");
+/**
+ * Transition-to-execute reminder injected on the first user turn after
+ * PLANNING → EXECUTING. Modeled on opencode's `build-switch.txt`:
+ *
+ *   "Your operational mode has changed from plan to build. You are no
+ *    longer in read-only mode. You are permitted to make file changes,
+ *    run shell commands, and utilize your arsenal of tools as needed."
+ *
+ * Critically, this reminder tells the agent to re-read the plan file
+ * and start executing it. Without the re-read, LLMs sometimes try to
+ * re-derive the plan from memory, which is slower and drifts.
+ */
+export function buildExecuteReminder(planFilePath) {
+    return `
+<system-reminder>
+Your operational mode has changed from plan to build. You are no longer in
+read-only mode. You are permitted to make file changes, run shell commands,
+and use any available tool.
+
+The approved plan is at:
+
+  ${planFilePath}
+
+Re-read that file now. Then execute its "Implementation steps" section, one
+step at a time, in order. Rules:
+
+- Before each tool call, re-read the current step from the plan. If you are
+  about to do something the plan does not say, stop and ask.
+- After completing a step, post a one-line progress update: "Step N/M
+  complete: <one-sentence outcome>"
+- If a step fails, stop. Diagnose and ask the user whether to fix in place,
+  skip, or revise the plan.
+- The plan is the source of truth. Drift is a bug.
+
+Start by reading ${planFilePath}. Do not restate the plan back to the user —
+just start executing.
+</system-reminder>
+`.trim();
+}
+/** Legacy alias. */
+export const EXECUTE_SYSTEM_PROMPT_HEADER = "see buildExecuteReminder(planFilePath)";
+/**
+ * Build an execution-mode prompt that appends the actual plan.md content
+ * verbatim. Used by downstream tools that need the plan inline rather
+ * than via a file-path reference.
+ */
+export function buildExecuteSystemPrompt(planContent) {
+    return `${buildExecuteReminder(".orient-cli/plans/current.md")}\n\n---\n\n${planContent.trim()}\n`;
+}
+// ============================================================================
+// Display helpers
+// ============================================================================
+/**
+ * Render a short multi-line status summary for /plan.status output.
+ */
+export function renderStatus(session) {
+    if (!session) {
+        return "No active plan. Run `/plan <goal description>` to start planning.";
+    }
+    const stepCount = session.steps.length;
+    const done = session.steps.filter((s) => s.status === "completed").length;
+    const currentStep = session.currentStepIndex >= 0 && session.currentStepIndex < stepCount
+        ? session.steps[session.currentStepIndex]
+        : undefined;
+    const lines = [`State: ${session.state}`, `Goal: ${session.goal}`, `Steps: ${done}/${stepCount} complete`];
+    if (currentStep) {
+        lines.push(`Current: ${currentStep.description}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=plan-execute.js.map

package/dist/orient/plan-execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-execute.js","sourceRoot":"","sources":["../../src/orient/plan-execute.ts"],"names":[],"mappings":"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"}

package/dist/orient/tiers.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Verbosity tier system
+ * ======================
+ *
+ * Three tiers govern how many questions the orientation wizard asks the
+ * user at each phase entry, and which markdown template variant scaffolds
+ * the phase's artifacts.
+ *
+ * Tier definitions (from Brief.md §6):
+ *   - Tier 1 (fast):      ≤ 5 questions (target 3)
+ *   - Tier 2 (balanced):  5-7 questions
+ *   - Tier 3 (thorough):  8-10 questions
+ *
+ * A tier is chosen at packet creation and may be overridden at each phase
+ * transition. The override persists on the packet config so subsequent
+ * entries to the same phase (after a resume or /clear) remember the choice.
+ *
+ * Templates live at:
+ *   schemas/orient-standard/templates-tier-1/<artifact>
+ *   schemas/orient-standard/templates-tier-2/<artifact>
+ *   schemas/orient-standard/templates-tier-3/<artifact>
+ *
+ * If a tier-specific template is missing, resolution falls back to
+ * templates-tier-2, then to templates/ (legacy single-template dir).
+ */
+import type { PacketConfig, WorkflowVariant } from "./types.js";
+export type Tier = 1 | 2 | 3;
+export type TierLabel = "fast" | "balanced" | "thorough";
+export declare const TIER_LABELS: Record<Tier, TierLabel>;
+/**
+ * Per-tier metadata used by the wizard to size question banks and
+ * render the tier picker.
+ */
+export interface TierSpec {
+    tier: Tier;
+    label: TierLabel;
+    digit: "1" | "2" | "3";
+    summary: string;
+    questionBudget: {
+        min: number;
+        max: number;
+        target: number;
+    };
+}
+export declare const TIERS: Record<Tier, TierSpec>;
+/**
+ * Tier config stored on PacketConfig. Default is the packet-wide fallback;
+ * phase-specific overrides in `phases` take precedence when present.
+ */
+export interface TierConfig {
+    default: Tier;
+    phases?: Partial<Record<string, Tier>>;
+}
+/**
+ * Read the effective tier for a given phase on a packet.
+ * Preference order:
+ *   1. phase-specific override
+ *   2. packet default
+ *   3. tier 2 (balanced) as the code-level ultimate fallback
+ */
+export declare function getEffectiveTier(config: PacketConfig & {
+    tier?: TierConfig;
+}, phase: string): Tier;
+/**
+ * Set the tier for a given phase on a packet (mutating). Callers are
+ * expected to persist via writePacketConfig() after.
+ */
+export declare function setPhaseTier(config: PacketConfig & {
+    tier?: TierConfig;
+}, phase: string, tier: Tier): PacketConfig & {
+    tier: TierConfig;
+};
+/**
+ * Set the packet-level default tier (used at packet creation).
+ */
+export declare function setDefaultTier(config: PacketConfig & {
+    tier?: TierConfig;
+}, tier: Tier): PacketConfig & {
+    tier: TierConfig;
+};
+/**
+ * Resolve the path to a tier-specific template for an artifact.
+ * Falls back through: templates-tier-N → templates-tier-2 → templates.
+ *
+ * @param templatesRoot  base directory containing the tier-indexed subdirs,
+ *                       typically the output of getTemplatesDir(variant)
+ *                       from package-paths.ts (but without the trailing
+ *                       /templates suffix — callers pass the schema root).
+ * @param variant        workflow variant ("standard" / "minimal" / "full")
+ * @param tier           resolved tier for the current phase
+ * @param artifactFile   artifact filename (e.g. "Brief.md")
+ */
+export declare function resolveTemplatePath(schemasRoot: string, variant: WorkflowVariant, tier: Tier, artifactFile: string): string | null;
+/**
+ * Build the ctx.ui.select() option array for the tier picker, in tier order.
+ * The label encodes the digit the user types to pick, which makes the UX
+ * match the brief's promise: "Just type 1, 2, or 3."
+ */
+export declare function buildTierSelectOptions(): string[];
+/**
+ * Parse a tier-selector option back to a Tier. The option strings are
+ * line-matched against TIERS[n].summary; a startsWith("<digit>") check
+ * handles trivial "user typed the digit" cases as well.
+ */
+export declare function parseTierFromSelection(selection: string): Tier | null;
+/**
+ * Human-readable summary of a tier's budget, used in confirmation messages.
+ */
+export declare function describeTierBudget(tier: Tier): string;

package/dist/orient/tiers.js

@@ -0,0 +1,162 @@
+/**
+ * Verbosity tier system
+ * ======================
+ *
+ * Three tiers govern how many questions the orientation wizard asks the
+ * user at each phase entry, and which markdown template variant scaffolds
+ * the phase's artifacts.
+ *
+ * Tier definitions (from Brief.md §6):
+ *   - Tier 1 (fast):      ≤ 5 questions (target 3)
+ *   - Tier 2 (balanced):  5-7 questions
+ *   - Tier 3 (thorough):  8-10 questions
+ *
+ * A tier is chosen at packet creation and may be overridden at each phase
+ * transition. The override persists on the packet config so subsequent
+ * entries to the same phase (after a resume or /clear) remember the choice.
+ *
+ * Templates live at:
+ *   schemas/orient-standard/templates-tier-1/<artifact>
+ *   schemas/orient-standard/templates-tier-2/<artifact>
+ *   schemas/orient-standard/templates-tier-3/<artifact>
+ *
+ * If a tier-specific template is missing, resolution falls back to
+ * templates-tier-2, then to templates/ (legacy single-template dir).
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export const TIER_LABELS = {
+    1: "fast",
+    2: "balanced",
+    3: "thorough",
+};
+export const TIERS = {
+    1: {
+        tier: 1,
+        label: "fast",
+        digit: "1",
+        summary: "fast — 3 questions per phase, minimum-viable spec, ship in under 10 minutes",
+        questionBudget: { min: 3, max: 5, target: 3 },
+    },
+    2: {
+        tier: 2,
+        label: "balanced",
+        digit: "2",
+        summary: "balanced — 5-7 questions per phase, spec-kit-style draft, most feature work",
+        questionBudget: { min: 5, max: 7, target: 6 },
+    },
+    3: {
+        tier: 3,
+        label: "thorough",
+        digit: "3",
+        summary: "thorough — 8-10 questions per phase, full spec-kit template, high-risk changes",
+        questionBudget: { min: 8, max: 10, target: 9 },
+    },
+};
+// ============================================================================
+// Persistence accessors (PacketConfig is extended via declaration merging
+// in orient-extension-types.d.ts — see comment below)
+// ============================================================================
+/**
+ * Read the effective tier for a given phase on a packet.
+ * Preference order:
+ *   1. phase-specific override
+ *   2. packet default
+ *   3. tier 2 (balanced) as the code-level ultimate fallback
+ */
+export function getEffectiveTier(config, phase) {
+    const override = config.tier?.phases?.[phase];
+    if (override)
+        return override;
+    if (config.tier?.default)
+        return config.tier.default;
+    return 2;
+}
+/**
+ * Set the tier for a given phase on a packet (mutating). Callers are
+ * expected to persist via writePacketConfig() after.
+ */
+export function setPhaseTier(config, phase, tier) {
+    const tierConfig = config.tier ?? { default: tier, phases: {} };
+    tierConfig.phases = { ...(tierConfig.phases ?? {}), [phase]: tier };
+    return { ...config, tier: tierConfig };
+}
+/**
+ * Set the packet-level default tier (used at packet creation).
+ */
+export function setDefaultTier(config, tier) {
+    const tierConfig = { default: tier, phases: config.tier?.phases ?? {} };
+    return { ...config, tier: tierConfig };
+}
+// ============================================================================
+// Template resolution
+// ============================================================================
+/**
+ * Resolve the path to a tier-specific template for an artifact.
+ * Falls back through: templates-tier-N → templates-tier-2 → templates.
+ *
+ * @param templatesRoot  base directory containing the tier-indexed subdirs,
+ *                       typically the output of getTemplatesDir(variant)
+ *                       from package-paths.ts (but without the trailing
+ *                       /templates suffix — callers pass the schema root).
+ * @param variant        workflow variant ("standard" / "minimal" / "full")
+ * @param tier           resolved tier for the current phase
+ * @param artifactFile   artifact filename (e.g. "Brief.md")
+ */
+export function resolveTemplatePath(schemasRoot, variant, tier, artifactFile) {
+    const templateFile = artifactFile.toLowerCase().replace(/ /g, "-");
+    const tierDirs = [`templates-tier-${tier}`, "templates-tier-2", "templates"];
+    for (const dir of tierDirs) {
+        const candidate = join(schemasRoot, `orient-${variant}`, dir, templateFile);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+// ============================================================================
+// Wizard helpers
+// ============================================================================
+/**
+ * Build the ctx.ui.select() option array for the tier picker, in tier order.
+ * The label encodes the digit the user types to pick, which makes the UX
+ * match the brief's promise: "Just type 1, 2, or 3."
+ */
+export function buildTierSelectOptions() {
+    return [TIERS[1].summary, TIERS[2].summary, TIERS[3].summary];
+}
+/**
+ * Parse a tier-selector option back to a Tier. The option strings are
+ * line-matched against TIERS[n].summary; a startsWith("<digit>") check
+ * handles trivial "user typed the digit" cases as well.
+ */
+export function parseTierFromSelection(selection) {
+    if (!selection)
+        return null;
+    const trimmed = selection.trim();
+    if (trimmed.startsWith("1") || trimmed.startsWith(TIERS[1].summary))
+        return 1;
+    if (trimmed.startsWith("2") || trimmed.startsWith(TIERS[2].summary))
+        return 2;
+    if (trimmed.startsWith("3") || trimmed.startsWith(TIERS[3].summary))
+        return 3;
+    // Fallback: look for bare digit anywhere in the string.
+    const digit = trimmed.match(/[123]/)?.[0];
+    if (digit === "1")
+        return 1;
+    if (digit === "2")
+        return 2;
+    if (digit === "3")
+        return 3;
+    return null;
+}
+/**
+ * Human-readable summary of a tier's budget, used in confirmation messages.
+ */
+export function describeTierBudget(tier) {
+    const spec = TIERS[tier];
+    const { min, max, target } = spec.questionBudget;
+    if (min === max)
+        return `${min} questions (fast-track)`;
+    return `${min}-${max} questions (target ${target})`;
+}
+//# sourceMappingURL=tiers.js.map

package/dist/orient/tiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiers.js","sourceRoot":"","sources":["../../src/orient/tiers.ts"],"names":[],"mappings":"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"}