procedure-cli 0.1.0

package/src/steps/product-context.tsx

@@ -0,0 +1,182 @@
+import React, { useState } from "react";
+import { Text } from "ink";
+import { TextInput } from "@inkjs/ui";
+import { GutterLine } from "../components/gutter-line.js";
+import { GutteredMultiSelect } from "../components/guttered-select.js";
+import type { WizardAnswers } from "../lib/types.js";
+
+interface Props {
+  initialValues?: Partial<WizardAnswers>;
+  onComplete: (answers: Partial<WizardAnswers>) => void;
+}
+
+type Phase = "problem" | "users" | "techStack" | "coreFeatures" | "nonGoals";
+
+const TECH_STACK_OPTIONS = [
+  { label: "React", value: "React", description: "UI component library" },
+  { label: "Next.js", value: "Next.js", description: "Full-stack React framework" },
+  { label: "Vue", value: "Vue", description: "Progressive UI framework" },
+  { label: "Svelte", value: "Svelte", description: "Compile-time UI framework" },
+  { label: "Node.js", value: "Node.js", description: "Server-side JavaScript runtime" },
+  { label: "Express", value: "Express", description: "Minimal Node.js web framework" },
+  { label: "Fastify", value: "Fastify", description: "High-performance Node.js framework" },
+  { label: "PostgreSQL", value: "PostgreSQL", description: "Relational database" },
+  { label: "MongoDB", value: "MongoDB", description: "Document database" },
+  { label: "Redis", value: "Redis", description: "In-memory data store / cache" },
+  { label: "Supabase", value: "Supabase", description: "Open-source Firebase alternative" },
+  { label: "Prisma", value: "Prisma", description: "TypeScript ORM" },
+  { label: "Docker", value: "Docker", description: "Container platform" },
+  { label: "Tailwind CSS", value: "Tailwind CSS", description: "Utility-first CSS framework" },
+  { label: "TypeScript", value: "TypeScript", description: "Typed JavaScript superset" },
+  { label: "Python", value: "Python", description: "General-purpose language" },
+  { label: "Go", value: "Go", description: "Systems programming language" },
+  { label: "Rust", value: "Rust", description: "Memory-safe systems language" },
+];
+
+const PHASE_ORDER: Phase[] = ["problem", "users", "techStack", "coreFeatures", "nonGoals"];
+
+export default function ProductContext({ initialValues, onComplete }: Props) {
+  const [phaseIndex, setPhaseIndex] = useState(0);
+  const [answers, setAnswers] = useState<Record<string, string>>({});
+  const [error, setError] = useState("");
+
+  // Prefill tech stack from Stack & Style selections (language + framework)
+  const prefillTechStack: string[] = [];
+  if (initialValues?.language) {
+    const match = TECH_STACK_OPTIONS.find(
+      (o) => o.value.toLowerCase() === initialValues.language!.toLowerCase()
+    );
+    if (match) prefillTechStack.push(match.value);
+  }
+  if (initialValues?.framework) {
+    const match = TECH_STACK_OPTIONS.find(
+      (o) => o.value.toLowerCase() === initialValues.framework!.toLowerCase()
+    );
+    if (match) prefillTechStack.push(match.value);
+  }
+
+  const currentPhase = PHASE_ORDER[phaseIndex]!;
+
+  function advanceToNext(key: string, value: string) {
+    const next = { ...answers, [key]: value };
+    setAnswers(next);
+    setError("");
+
+    if (phaseIndex < PHASE_ORDER.length - 1) {
+      setPhaseIndex(phaseIndex + 1);
+    } else {
+      onComplete({
+        problem: next.problem,
+        users: next.users,
+        techStack: next.techStack,
+        coreFeatures: (next.coreFeatures || "")
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean),
+        nonGoals: (next.nonGoals || "")
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean),
+        userStories: [],
+        envVars: [],
+      });
+    }
+  }
+
+  function handleTextSubmit(key: string, required: boolean) {
+    return (value: string) => {
+      const val = value.trim();
+      if (required && !val) {
+        setError(`This field is required`);
+        return;
+      }
+      advanceToNext(key, val);
+    };
+  }
+
+  function handleTechStackSubmit(values: string[]) {
+    advanceToNext("techStack", values.join(", "));
+  }
+
+  // Build completed fields display
+  const completedFields = PHASE_ORDER.slice(0, phaseIndex).map((key) => (
+    <GutterLine key={key}>
+      <Text dimColor>
+        {key === "problem" && `Problem: ${answers[key]}`}
+        {key === "users" && `Users: ${answers[key]}`}
+        {key === "techStack" && `Tech stack: ${answers[key]}`}
+        {key === "coreFeatures" && `Core features: ${answers[key]}`}
+        {key === "nonGoals" && `Non-goals: ${answers[key]}`}
+      </Text>
+    </GutterLine>
+  ));
+
+  const usersPlaceholder = answers["problem"]
+    ? `People affected by: ${answers["problem"]}`
+    : "e.g. Developers, PMs, designers...";
+
+  return (
+    <>
+      {completedFields}
+
+      {currentPhase === "problem" && (
+        <GutterLine>
+          <Text bold>What problem does this solve? </Text>
+          <TextInput
+            placeholder="Describe the core problem..."
+            onSubmit={handleTextSubmit("problem", true)}
+          />
+        </GutterLine>
+      )}
+
+      {currentPhase === "users" && (
+        <GutterLine>
+          <Text bold>Who are the users? </Text>
+          <TextInput
+            placeholder={usersPlaceholder}
+            onSubmit={handleTextSubmit("users", true)}
+          />
+        </GutterLine>
+      )}
+
+      {currentPhase === "techStack" && (
+        <>
+          <GutterLine>
+            <Text bold>Tech stack:</Text>
+          </GutterLine>
+          <GutteredMultiSelect
+            options={TECH_STACK_OPTIONS}
+            initialSelected={prefillTechStack}
+            onSubmit={handleTechStackSubmit}
+          />
+        </>
+      )}
+
+      {currentPhase === "coreFeatures" && (
+        <GutterLine>
+          <Text bold>Core features (comma-separated): </Text>
+          <TextInput
+            placeholder="e.g. Auth, Dashboard, API..."
+            onSubmit={handleTextSubmit("coreFeatures", true)}
+          />
+        </GutterLine>
+      )}
+
+      {currentPhase === "nonGoals" && (
+        <GutterLine>
+          <Text bold>Non-goals (comma-separated): </Text>
+          <TextInput
+            placeholder="e.g. Mobile app, Real-time sync..."
+            onSubmit={handleTextSubmit("nonGoals", false)}
+          />
+        </GutterLine>
+      )}
+
+      {error && (
+        <GutterLine>
+          <Text color="red">{error}</Text>
+        </GutterLine>
+      )}
+    </>
+  );
+}

package/src/steps/project-info.tsx

@@ -0,0 +1,135 @@
+import React, { useState } from "react";
+import { Text } from "ink";
+import { TextInput } from "@inkjs/ui";
+import { GutterLine } from "../components/gutter-line.js";
+import { GutteredSelect } from "../components/guttered-select.js";
+import type { WizardAnswers } from "../lib/types.js";
+
+interface Props {
+  onComplete: (answers: Partial<WizardAnswers>) => void;
+}
+
+type Step = "projectName" | "description" | "packageManager" | "license";
+
+const STEP_ORDER: Step[] = [
+  "projectName",
+  "description",
+  "packageManager",
+  "license",
+];
+
+const PACKAGE_MANAGER_OPTIONS = [
+  { label: "npm", value: "npm" },
+  { label: "pnpm", value: "pnpm" },
+  { label: "bun", value: "bun" },
+  { label: "yarn", value: "yarn" },
+];
+
+const LICENSE_OPTIONS = [
+  { label: "MIT — Permissive, allows commercial use", value: "MIT" },
+  { label: "ISC — Simplified MIT, minimal restrictions", value: "ISC" },
+  { label: "Apache-2.0 — Permissive with patent protection", value: "Apache-2.0" },
+  { label: "GPL-3.0 — Copyleft, requires source disclosure", value: "GPL-3.0" },
+  { label: "Unlicense — Public domain, no restrictions", value: "Unlicense" },
+];
+
+export default function ProjectInfo({ onComplete }: Props) {
+  const [stepIndex, setStepIndex] = useState(0);
+  const [answers, setAnswers] = useState<Record<string, string>>({});
+  const [error, setError] = useState("");
+
+  const currentStep = STEP_ORDER[stepIndex]!;
+
+  function advance(key: string, value: string) {
+    const next = { ...answers, [key]: value };
+    setAnswers(next);
+    setError("");
+
+    if (stepIndex < STEP_ORDER.length - 1) {
+      setStepIndex(stepIndex + 1);
+    } else {
+      onComplete(next as unknown as Partial<WizardAnswers>);
+    }
+  }
+
+  function handleTextSubmit(value: string) {
+    const val = value.trim();
+    if (!val) {
+      setError(
+        currentStep === "projectName"
+          ? "Project name is required"
+          : "Description is required"
+      );
+      return;
+    }
+    advance(currentStep, val);
+  }
+
+  function handleSelectChange(key: string) {
+    return (value: string) => {
+      advance(key, value);
+    };
+  }
+
+  // Render completed fields
+  const completed = STEP_ORDER.slice(0, stepIndex).map((key) => (
+    <GutterLine key={key}>
+      <Text dimColor>
+        {key === "projectName" && `Project name: ${answers[key]}`}
+        {key === "description" && `Description: ${answers[key]}`}
+        {key === "packageManager" && `Package manager: ${answers[key]}`}
+        {key === "license" && `License: ${answers[key]}`}
+      </Text>
+    </GutterLine>
+  ));
+
+  return (
+    <>
+      {completed}
+
+      {currentStep === "projectName" && (
+        <GutterLine>
+          <Text bold>Project name: </Text>
+          <TextInput placeholder="..." onSubmit={handleTextSubmit} />
+        </GutterLine>
+      )}
+
+      {currentStep === "description" && (
+        <GutterLine>
+          <Text bold>One-line description: </Text>
+          <TextInput placeholder="..." onSubmit={handleTextSubmit} />
+        </GutterLine>
+      )}
+
+      {currentStep === "packageManager" && (
+        <>
+          <GutterLine>
+            <Text bold>Package manager:</Text>
+          </GutterLine>
+          <GutteredSelect
+            options={PACKAGE_MANAGER_OPTIONS}
+            onChange={handleSelectChange("packageManager")}
+          />
+        </>
+      )}
+
+      {currentStep === "license" && (
+        <>
+          <GutterLine>
+            <Text bold>License:</Text>
+          </GutterLine>
+          <GutteredSelect
+            options={LICENSE_OPTIONS}
+            onChange={handleSelectChange("license")}
+          />
+        </>
+      )}
+
+      {error && (
+        <GutterLine>
+          <Text color="red">{error}</Text>
+        </GutterLine>
+      )}
+    </>
+  );
+}

package/src/steps/stack-style.tsx

@@ -0,0 +1,117 @@
+import React, { useState } from "react";
+import { Text } from "ink";
+import { TextInput } from "@inkjs/ui";
+import { GutterLine } from "../components/gutter-line.js";
+import { GutteredSelect } from "../components/guttered-select.js";
+import type { WizardAnswers } from "../lib/types.js";
+
+interface Props {
+  onComplete: (answers: Partial<WizardAnswers>) => void;
+}
+
+type Mode = "choosing" | "quickstart" | "advanced";
+type AdvancedField = "language" | "framework" | "codeStyle";
+
+const PRESET_OPTIONS = [
+  { label: "TypeScript + Node.js", value: "typescript-node" },
+];
+
+const ADVANCED_FIELDS: { key: AdvancedField; label: string }[] = [
+  { key: "language", label: "Language" },
+  { key: "framework", label: "Framework" },
+  { key: "codeStyle", label: "Code style conventions (comma-separated)" },
+];
+
+const PRESETS: Record<string, Partial<WizardAnswers>> = {
+  "typescript-node": {
+    language: "TypeScript",
+    framework: "Node.js",
+    codeStyle: [
+      "TypeScript strict mode, ESM imports",
+      "camelCase for variables, PascalCase for types",
+      "stdlib -> external -> internal import ordering",
+      "Return errors, don't throw",
+    ],
+    buildCommand: "npm run build",
+    testCommand: "npm run test",
+    typecheckCommand: "npm run typecheck",
+    lintCommand: "npm run lint",
+  },
+};
+
+export default function StackStyle({ onComplete }: Props) {
+  const [mode, setMode] = useState<Mode>("choosing");
+  const [advancedIndex, setAdvancedIndex] = useState(0);
+  const [answers, setAnswers] = useState<Record<string, string>>({});
+
+  if (mode === "choosing") {
+    return (
+      <>
+        <GutterLine>
+          <Text bold>Setup mode:</Text>
+        </GutterLine>
+        <GutteredSelect
+          options={[
+            { label: "QuickStart (use a preset)", value: "quickstart" },
+            { label: "Advanced (manual config)", value: "advanced" },
+          ]}
+          onChange={(val) => setMode(val as Mode)}
+        />
+      </>
+    );
+  }
+
+  if (mode === "quickstart") {
+    return (
+      <>
+        <GutterLine>
+          <Text bold>Select a stack preset:</Text>
+        </GutterLine>
+        <GutteredSelect
+          options={PRESET_OPTIONS}
+          onChange={(val) => {
+            const preset = PRESETS[val];
+            if (preset) {
+              onComplete(preset);
+            }
+          }}
+        />
+      </>
+    );
+  }
+
+  // Advanced mode
+  const current = ADVANCED_FIELDS[advancedIndex];
+
+  function handleSubmit(value: string) {
+    const next = { ...answers, [current!.key]: value };
+    setAnswers(next);
+
+    if (advancedIndex < ADVANCED_FIELDS.length - 1) {
+      setAdvancedIndex(advancedIndex + 1);
+    } else {
+      onComplete({
+        language: next.language,
+        framework: next.framework,
+        codeStyle: (next.codeStyle || "").split(",").map((s) => s.trim()),
+      });
+    }
+  }
+
+  return (
+    <>
+      {ADVANCED_FIELDS.slice(0, advancedIndex).map((f) => (
+        <GutterLine key={f.key}>
+          <Text dimColor>
+            {f.label}: {answers[f.key]}
+          </Text>
+        </GutterLine>
+      ))}
+
+      <GutterLine>
+        <Text bold>{current!.label}: </Text>
+        <TextInput placeholder="..." onSubmit={handleSubmit} />
+      </GutterLine>
+    </>
+  );
+}

package/templates/.env.example.hbs

@@ -0,0 +1,6 @@
+# Environment Variables
+{{#each envVars}}
+
+# {{this.comment}}
+{{this.key}}=
+{{/each}}

package/templates/CLAUDE.md.hbs

@@ -0,0 +1,105 @@
+# {{projectName}}
+
+{{description}}
+
+See docs/PRD.md for product requirements and docs/USER-STORIES.md for user stories with acceptance criteria.
+
+## Build & Test
+
+```bash
+{{buildCommand}}              # Build
+{{typecheckCommand}}           # Typecheck (fast — run first)
+{{testCommand}} -- -t "name"   # Test (specific)
+{{testCommand}}                # Test (full suite)
+{{lintCommand}}                # Lint
+{{prCommand}}                  # Before creating a PR
+```
+
+## Code Style
+
+{{#each codeStyle}}
+- {{{this}}}
+{{/each}}
+
+## Architecture
+
+{{{architecture}}}
+
+## Workflow
+
+### Planning
+- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
+- If something goes sideways, STOP and re-plan — don't keep pushing
+- A good plan lets you one-shot the implementation
+
+### Verification
+- Never mark a task complete without proving it works
+- Run tests, check logs, demonstrate correctness
+- Ask yourself: "Would a staff engineer approve this?"
+
+### Self-Improvement
+- After ANY correction from the user: update the Lessons section below
+- Write rules that prevent the same mistake from recurring
+
+### Bug Fixing
+- Given a bug report: just fix it. Don't ask for hand-holding
+- Point at logs, errors, failing tests — then resolve them
+
+### Elegance
+- For non-trivial changes: pause and ask "is there a more elegant way?"
+- If a fix feels hacky, step back and implement the clean solution
+- Skip this for simple, obvious fixes — don't over-engineer
+
+## Task Management
+
+### Solo Work
+1. Plan first (plan mode for complex tasks)
+2. Track progress with TaskCreate/TaskUpdate for multi-step work
+3. Verify before claiming done
+4. Update Lessons after corrections
+
+### Agent Teams
+1. Plan-then-team: design approach BEFORE spawning a team
+2. Each task = one clear deliverable with verification steps
+3. File ownership: each teammate owns specific files — NEVER have two edit the same file
+4. Include file paths and constraints in task descriptions — teammates don't inherit context
+5. DMs by default, broadcast only for critical blocking issues
+6. 3-5 teammates max
+
+## Code Review & Fix Logging
+
+Two tracking files live at the project root. Both are append-only logs — never delete or rewrite past entries.
+
+### CODE-REVIEW.md — review findings
+- Created/appended during code review sessions.
+- Entry ID format: `CR-YYYYMMDD-###` (zero-padded sequence per day).
+- Findings ordered by severity (`High`, `Medium`, `Low`).
+- Every finding includes `file:line` evidence, a clear recommendation, and `Status` (`New`, `Still Open`, `Fixed`, `Regressed`, `Not Reproducible`).
+
+### CODE-FIXED.md — fix results
+- Created/appended when fixing findings from CODE-REVIEW.md.
+- Entry ID format: `CF-YYYYMMDD-###`.
+- Each entry references its source review by `CR-` Entry ID — do NOT re-describe findings, only document actions taken.
+- Fixed findings include `file:line` for every change made.
+- Deferred findings include rationale and a revisit trigger.
+- Verification section must confirm `{{typecheckCommand}}` + `{{buildCommand}}` status after fixes.
+
+### Procedure
+1. **Reviewing**:
+   - **First**: Read CODE-REVIEW.md → Read CODE-FIXED.md → understand current state of findings and fixes.
+   - **Then**: Read codebase → append findings to CODE-REVIEW.md with a new `CR-` entry (write to CODE-REVIEW.md only, never modify CODE-FIXED.md).
+   - **Never** fix code during a reviewing process.
+2. **Fixing**:
+   - **First**: Read CODE-REVIEW.md → Read CODE-FIXED.md → identify unfixed findings.
+   - **Then**: Fix only unfixed findings → append a new `CF-` entry to CODE-FIXED.md (write to CODE-FIXED.md only, never modify CODE-REVIEW.md).
+   - **Never** perform a code review during a fixing process.
+
+## Core Principles
+
+- **Simplicity First**: Make every change as simple as possible. Minimal code impact.
+- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
+- **Minimal Impact**: Changes should only touch what's necessary.
+
+## Lessons
+
+<!-- After ANY correction, add a rule here. This section compounds over time. -->

package/templates/README.md.hbs

@@ -0,0 +1,26 @@
+# {{projectName}}
+
+{{description}}
+
+## Getting Started
+
+```bash
+{{packageManager}} install
+{{buildCommand}}
+```
+
+## Development
+
+```bash
+{{lintCommand}}                # Lint
+{{testCommand}}                # Run tests
+{{lintCommand}} && {{testCommand}}  # Before creating a PR
+```
+
+## Architecture
+
+{{{architectureNotes}}}
+
+## License
+
+{{license}}

package/templates/docs/PRD.md.hbs

@@ -0,0 +1,29 @@
+# {{projectName}} — Product Requirements
+
+## Vision
+
+{{description}}
+
+## Problem
+
+{{problem}}
+
+## Users
+
+{{users}}
+
+## Core Features
+
+{{#each coreFeatures}}
+- {{{this}}}
+{{/each}}
+
+## Non-Goals
+
+{{#each nonGoals}}
+- {{{this}}}
+{{/each}}
+
+## Tech Stack
+
+{{techStack}}

package/templates/docs/USER-STORIES.md.hbs

@@ -0,0 +1,46 @@
+# {{projectName}} — User Stories
+
+{{#if userStories.length}}
+{{#each userStories}}
+## {{title}}
+
+**As a** {{asA}}
+**I want** {{iWant}}
+**So that** {{soThat}}
+
+### Feature: {{feature}}
+
+{{#each scenarios}}
+```gherkin
+Scenario: {{this.name}}
+  Given {{this.given}}
+  When {{this.when}}
+  Then {{this.then}}
+```
+
+{{/each}}
+{{/each}}
+{{else}}
+<!-- TODO: Add user stories for {{projectName}} -->
+<!-- Use the format below to define acceptance criteria in Gherkin style. -->
+
+## Example: User can perform core action
+
+**As a** user
+**I want** to perform a core action
+**So that** I can achieve my goal
+
+### Feature: Core Action
+
+```gherkin
+Scenario: Successful core action
+  Given the user is authenticated
+  When the user performs the core action
+  Then the system processes the request
+```
+
+---
+
+> Replace this example with real user stories for your project.
+> Each story should follow the **As a / I want / So that** format with Gherkin scenarios.
+{{/if}}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "jsx": "react-jsx",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}