@shenlee/devcrew 0.1.0

package/packages/core/src/config.ts

@@ -0,0 +1,56 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+
+import { configPath, ensureProjectDirectories } from "./paths.js";
+import type { DevCrewConfig } from "./types.js";
+
+export const DEFAULT_CONFIG: DevCrewConfig = {
+  version: 1,
+  defaultBackend: "host-preferred",
+  executionMode: "plan",
+  verifyCommands: [],
+  lintCommands: [],
+  coverageCommands: [],
+  workflow: {
+    gates: ["requirements", "architecture", "implementation", "testing"],
+    artifactDirectory: "docs/devcrew",
+  },
+};
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureConfig(cwd: string): Promise<DevCrewConfig> {
+  await ensureProjectDirectories(cwd);
+  const path = configPath(cwd);
+  if (!(await exists(path))) {
+    await writeFile(path, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, "utf8");
+    return DEFAULT_CONFIG;
+  }
+  return readConfig(cwd);
+}
+
+export async function readConfig(cwd: string): Promise<DevCrewConfig> {
+  const raw = await readFile(configPath(cwd), "utf8");
+  const parsed = JSON.parse(raw) as DevCrewConfig;
+  if (parsed.version !== 1) {
+    throw new Error("Unsupported .devcrew/config.json version");
+  }
+  return {
+    ...DEFAULT_CONFIG,
+    ...parsed,
+    executionMode: parsed.executionMode ?? "plan",
+    verifyCommands: Array.isArray(parsed.verifyCommands) ? parsed.verifyCommands : [],
+    lintCommands: Array.isArray(parsed.lintCommands) ? parsed.lintCommands : [],
+    coverageCommands: Array.isArray(parsed.coverageCommands) ? parsed.coverageCommands : [],
+    workflow: {
+      ...DEFAULT_CONFIG.workflow,
+      ...parsed.workflow,
+    },
+  };
+}

package/packages/core/src/index.ts

@@ -0,0 +1,11 @@
+export * from "./active-run.js";
+export * from "./artifacts.js";
+export * from "./config.js";
+export * from "./paths.js";
+export * from "./standards.js";
+export * from "./store.js";
+export * from "./types.js";
+export * from "./validation.js";
+export * from "./version.js";
+export * from "./verification.js";
+export * from "./workflow.js";

package/packages/core/src/paths.ts

@@ -0,0 +1,66 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { ArtifactName, RunState } from "./types.js";
+
+export function devcrewDir(cwd: string): string {
+  return join(cwd, ".devcrew");
+}
+
+export function runsDir(cwd: string): string {
+  return join(devcrewDir(cwd), "runs");
+}
+
+export function runDir(cwd: string, runId: string): string {
+  return join(runsDir(cwd), runId);
+}
+
+export function statePath(cwd: string, runId: string): string {
+  return join(runDir(cwd, runId), "state.json");
+}
+
+export function configPath(cwd: string): string {
+  return join(devcrewDir(cwd), "config.json");
+}
+
+export function activeRunPath(cwd: string): string {
+  return join(devcrewDir(cwd), "active-run.json");
+}
+
+export function standardsPath(cwd: string): string {
+  return join(devcrewDir(cwd), "standards.md");
+}
+
+export function docsRoot(cwd: string): string {
+  return join(cwd, "docs", "devcrew");
+}
+
+export function docsRunDir(cwd: string, runId: string): string {
+  return join(docsRoot(cwd), runId);
+}
+
+export function artifactPath(cwd: string, runId: string, artifact: ArtifactName): string {
+  const filenameByArtifact: Record<ArtifactName, string> = {
+    requirements: "requirements.md",
+    architecture: "architecture.md",
+    "implementation-plan": "implementation-plan.md",
+    "implementation-review": "implementation-review.md",
+    "test-report": "test-report.md",
+    acceptance: "acceptance.md",
+  };
+  return join(docsRunDir(cwd, runId), filenameByArtifact[artifact]);
+}
+
+export async function ensureRunDirectories(cwd: string, runId: string): Promise<void> {
+  await mkdir(runDir(cwd, runId), { recursive: true });
+  await mkdir(docsRunDir(cwd, runId), { recursive: true });
+}
+
+export async function ensureProjectDirectories(cwd: string): Promise<void> {
+  await mkdir(devcrewDir(cwd), { recursive: true });
+  await mkdir(docsRoot(cwd), { recursive: true });
+}
+
+export function relativeArtifactMap(state: RunState): Partial<Record<ArtifactName, string>> {
+  return state.artifacts;
+}

package/packages/core/src/standards.ts

@@ -0,0 +1,70 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { standardsPath } from "./paths.js";
+import type { StandardsDiscovery } from "./types.js";
+import { readPackageJson } from "./verification.js";
+
+async function readIfExists(path: string): Promise<string | undefined> {
+  try {
+    await access(path);
+    return readFile(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+function section(path: string, content: string): string {
+  return `## ${path}\n\n${content.trim()}\n`;
+}
+
+async function packageJsonSummary(cwd: string): Promise<string | undefined> {
+  const parsed = await readPackageJson(cwd);
+  if (!parsed) {
+    return undefined;
+  }
+  const scripts = Object.keys(parsed.scripts ?? {});
+  if (scripts.length === 0) {
+    return "package.json scripts: none";
+  }
+  return `package.json scripts: ${scripts.join(", ")}`;
+}
+
+export async function discoverStandards(cwd: string): Promise<StandardsDiscovery> {
+  const candidates = [
+    standardsPath(cwd),
+    join(cwd, "AGENTS.md"),
+    join(cwd, "CLAUDE.md"),
+    join(cwd, "README.md"),
+    join(cwd, "README"),
+    join(cwd, "pyproject.toml"),
+    join(cwd, "go.mod"),
+    join(cwd, "Cargo.toml"),
+  ];
+  const sources: string[] = [];
+  const sections: string[] = [];
+
+  for (const candidate of candidates) {
+    const content = await readIfExists(candidate);
+    if (content?.trim()) {
+      sources.push(candidate);
+      sections.push(section(candidate, content));
+    }
+  }
+
+  const packageSummary = await packageJsonSummary(cwd);
+  if (packageSummary) {
+    const packagePath = join(cwd, "package.json");
+    sources.push(packagePath);
+    sections.push(section(packagePath, packageSummary));
+  }
+
+  if (sections.length === 0) {
+    sections.push("No project standards were discovered. Follow the current repository style and ask before broad refactors.\n");
+  }
+
+  return {
+    sources,
+    combined: sections.join("\n"),
+  };
+}

package/packages/core/src/store.ts

@@ -0,0 +1,28 @@
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { ensureRunDirectories, statePath } from "./paths.js";
+import type { RunState } from "./types.js";
+
+export async function saveState(state: RunState): Promise<RunState> {
+  state.updatedAt = new Date().toISOString();
+  await ensureRunDirectories(state.cwd, state.runId);
+  const target = statePath(state.cwd, state.runId);
+  const temp = join(dirname(target), `.state.${process.pid}.${Date.now()}.tmp`);
+  await writeFile(temp, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  await rename(temp, target);
+  return state;
+}
+
+export async function loadState(cwd: string, runId: string): Promise<RunState> {
+  const raw = await readFile(statePath(cwd, runId), "utf8");
+  const parsed = JSON.parse(raw) as RunState;
+  return {
+    ...parsed,
+    executionMode: parsed.executionMode ?? "plan",
+    changedFiles: Array.isArray(parsed.changedFiles) ? parsed.changedFiles : [],
+    implementationDiff: typeof parsed.implementationDiff === "string" ? parsed.implementationDiff : "",
+    verification: Array.isArray(parsed.verification) ? parsed.verification : [],
+    lintResults: Array.isArray(parsed.lintResults) ? parsed.lintResults : [],
+  };
+}

package/packages/core/src/types.ts

@@ -0,0 +1,182 @@
+export const WORKFLOW_MODES = ["feature", "greenfield"] as const;
+export const EXECUTION_MODES = ["plan", "apply"] as const;
+export const HOSTS = ["codex", "claude"] as const;
+export const BACKENDS = ["codex", "claude", "local"] as const;
+export const PHASES = [
+  "requirements",
+  "architecture",
+  "implementation",
+  "testing",
+  "acceptance",
+  "complete",
+] as const;
+export const GATES = ["requirements", "architecture", "implementation", "testing"] as const;
+export const ARTIFACTS = [
+  "requirements",
+  "architecture",
+  "implementation-plan",
+  "implementation-review",
+  "test-report",
+  "acceptance",
+] as const;
+
+export type WorkflowMode = (typeof WORKFLOW_MODES)[number];
+export type ExecutionMode = (typeof EXECUTION_MODES)[number];
+export type Host = (typeof HOSTS)[number];
+export type BackendName = (typeof BACKENDS)[number];
+export type Phase = (typeof PHASES)[number];
+export type GateName = (typeof GATES)[number];
+export type ArtifactName = (typeof ARTIFACTS)[number];
+export type GateStatus = "not_started" | "pending" | "approved" | "rejected";
+export type RunStatus = "ready" | "awaiting_input" | "awaiting_approval" | "complete";
+
+export interface RoleSection {
+  heading: string;
+  description: string;
+}
+
+export const ROLE_SECTIONS: Record<Exclude<RoleResult["role"], "conductor">, RoleSection[]> = {
+  pm: [
+    { heading: "Functional Scope", description: "explicit In Scope and Out of Scope lists" },
+    { heading: "Users and Scenarios", description: "primary users and their key scenarios" },
+    { heading: "Acceptance Criteria", description: "testable criteria written as Given / When / Then" },
+    { heading: "Priorities", description: "classify each requirement as Must / Should / Could / Won't (MoSCoW)" },
+    { heading: "Open Questions", description: "unresolved clarifications for the requester" },
+  ],
+  architect: [
+    { heading: "Technical Decisions", description: "for each key decision record Decision, Options Considered, Choice, Rationale, and Trade-offs" },
+    { heading: "Interface Contracts", description: "for each interface give the signature, request/response schema, error contract, and data model" },
+    { heading: "Data Flow and Deployment", description: "data flow, deployment expectations, and rollback strategy" },
+    { heading: "Architecture Review Checklist", description: "how the design traces back to the approved requirements" },
+  ],
+  implementer: [
+    { heading: "Implementation Summary", description: "the smallest change that satisfies the approved architecture" },
+    { heading: "Standards Compliance", description: "follow discovered standards and lint/format rules; run available lint/format/typecheck and report results" },
+    { heading: "Changed Files", description: "every file you created or modified" },
+    { heading: "Tests Added or Updated", description: "tests covering success, edge, and failure paths" },
+  ],
+  tester: [
+    { heading: "Test Cases", description: "enumerate cases as a table with ID, Scenario, Type (happy/edge/failure/regression), and Expected result" },
+    { heading: "Coverage", description: "run the coverage command and report the coverage summary plus any gaps" },
+    { heading: "Verification Evidence", description: "exact commands, exit codes, and key output" },
+    { heading: "Known Risks", description: "residual risks and follow-ups" },
+  ],
+};
+
+export interface DevCrewConfig {
+  version: 1;
+  defaultBackend: "host-preferred" | BackendName;
+  executionMode: ExecutionMode;
+  verifyCommands: string[];
+  lintCommands: string[];
+  coverageCommands: string[];
+  workflow: {
+    gates: GateName[];
+    artifactDirectory: string;
+  };
+}
+
+export interface StandardsDiscovery {
+  sources: string[];
+  combined: string;
+}
+
+export interface RoleResult {
+  role: "conductor" | "pm" | "architect" | "implementer" | "tester";
+  backend: BackendName;
+  summary: string;
+  markdown: string;
+  usedFallback: boolean;
+}
+
+export interface WorkflowFeedback {
+  gate: GateName;
+  message: string;
+  createdAt: string;
+}
+
+export interface WorkflowApproval {
+  gate: GateName;
+  note?: string;
+  createdAt: string;
+}
+
+export interface WorkflowAnswer {
+  answer: string;
+  createdAt: string;
+}
+
+// Reused for both verification and lint results — the command shape is identical.
+export interface VerificationResult {
+  command: string;
+  exitCode: number;
+  output: string;
+  startedAt: string;
+  completedAt: string;
+}
+
+export interface RunState {
+  version: 1;
+  runId: string;
+  cwd: string;
+  host: Host;
+  mode: WorkflowMode;
+  executionMode: ExecutionMode;
+  backend: BackendName;
+  request: string;
+  phase: Phase;
+  status: RunStatus;
+  createdAt: string;
+  updatedAt: string;
+  gates: Record<GateName, GateStatus>;
+  artifacts: Partial<Record<ArtifactName, string>>;
+  roles: RoleResult[];
+  answers: WorkflowAnswer[];
+  approvals: WorkflowApproval[];
+  feedback: WorkflowFeedback[];
+  standards: StandardsDiscovery;
+  changedFiles: string[];
+  implementationDiff: string;
+  verification: VerificationResult[];
+  // VerificationResult is reused for lint output — same shape, different semantics.
+  lintResults: VerificationResult[];
+}
+
+export interface StartWorkflowInput {
+  cwd: string;
+  host: Host;
+  mode: WorkflowMode;
+  request: string;
+  backend?: BackendName;
+  executionMode?: ExecutionMode;
+}
+
+export interface RunRef {
+  cwd: string;
+  runId: string;
+}
+
+export interface ApproveWorkflowInput extends RunRef {
+  gate: GateName;
+  note?: string;
+}
+
+export interface RejectWorkflowInput extends RunRef {
+  gate: GateName;
+  feedback: string;
+}
+
+export interface AnswerWorkflowInput extends RunRef {
+  answer: string;
+}
+
+export interface ArtifactRef extends RunRef {
+  name: ArtifactName;
+}
+
+export interface ArtifactReadResult {
+  name: ArtifactName;
+  path: string;
+  content: string;
+  summary: string;
+}

package/packages/core/src/validation.ts

@@ -0,0 +1,79 @@
+import {
+  ARTIFACTS,
+  BACKENDS,
+  EXECUTION_MODES,
+  GATES,
+  HOSTS,
+  WORKFLOW_MODES,
+  type ArtifactName,
+  type BackendName,
+  type ExecutionMode,
+  type GateName,
+  type Host,
+  type WorkflowMode,
+} from "./types.js";
+
+function assertString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function oneOf<T extends readonly string[]>(value: unknown, field: string, values: T): T[number] {
+  if (typeof value !== "string" || !values.includes(value)) {
+    throw new Error(`${field} must be one of: ${values.join(", ")}`);
+  }
+  return value as T[number];
+}
+
+export function parseWorkflowMode(value: unknown): WorkflowMode {
+  return oneOf(value, "mode", WORKFLOW_MODES);
+}
+
+export function parseExecutionMode(value: unknown): ExecutionMode {
+  return oneOf(value, "executionMode", EXECUTION_MODES);
+}
+
+export function parseHost(value: unknown): Host {
+  return oneOf(value, "host", HOSTS);
+}
+
+export function parseBackend(value: unknown): BackendName {
+  return oneOf(value, "backend", BACKENDS);
+}
+
+export function parseGate(value: unknown): GateName {
+  return oneOf(value, "gate", GATES);
+}
+
+export function parseArtifactName(value: unknown): ArtifactName {
+  return oneOf(value, "name", ARTIFACTS);
+}
+
+export function parseCwd(value: unknown): string {
+  return assertString(value, "cwd");
+}
+
+export function parseRunId(value: unknown): string {
+  return assertString(value, "runId");
+}
+
+export function parseRequest(value: unknown): string {
+  return assertString(value, "request");
+}
+
+export function parseOptionalNote(value: unknown): string | undefined {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  return assertString(value, "note");
+}
+
+export function parseFeedback(value: unknown): string {
+  return assertString(value, "feedback");
+}
+
+export function parseAnswer(value: unknown): string {
+  return assertString(value, "answer");
+}

package/packages/core/src/verification.ts

@@ -0,0 +1,163 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+async function readIfExists(path: string): Promise<string | undefined> {
+  try {
+    await access(path);
+    return readFile(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function packageVerifyCommands(cwd: string): Promise<string[]> {
+  const raw = await readIfExists(join(cwd, "package.json"));
+  if (!raw) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw) as { scripts?: Record<string, string> };
+    const scripts = parsed.scripts ?? {};
+    if (scripts.validate) {
+      return ["npm run validate"];
+    }
+    if (scripts.test) {
+      return ["npm test"];
+    }
+    const commands: string[] = [];
+    if (scripts.typecheck) {
+      commands.push("npm run typecheck");
+    }
+    if (scripts.lint) {
+      commands.push("npm run lint");
+    }
+    return commands;
+  } catch {
+    return [];
+  }
+}
+
+async function pythonVerifyCommands(cwd: string): Promise<string[]> {
+  const pyproject = await readIfExists(join(cwd, "pyproject.toml"));
+  if (!pyproject) {
+    return [];
+  }
+  if (pyproject.includes("[tool.pytest") || pyproject.includes("pytest")) {
+    return ["python -m pytest"];
+  }
+  return [];
+}
+
+export async function discoverVerifyCommands(cwd: string): Promise<string[]> {
+  const packageCommands = await packageVerifyCommands(cwd);
+  if (packageCommands.length > 0) {
+    return packageCommands;
+  }
+  if (await exists(join(cwd, "go.mod"))) {
+    return ["go test ./..."];
+  }
+  if (await exists(join(cwd, "Cargo.toml"))) {
+    return ["cargo test"];
+  }
+  return pythonVerifyCommands(cwd);
+}
+
+export async function readPackageJson(cwd: string): Promise<{ scripts?: Record<string, string>; dependencies?: Record<string, string>; devDependencies?: Record<string, string> } | undefined> {
+  const raw = await readIfExists(join(cwd, "package.json"));
+  if (!raw) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(raw) as { scripts?: Record<string, string>; dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+  } catch {
+    return undefined;
+  }
+}
+
+async function packageLintCommands(cwd: string): Promise<string[]> {
+  const parsed = await readPackageJson(cwd);
+  if (!parsed) {
+    return [];
+  }
+  const scripts = parsed.scripts ?? {};
+  const commands: string[] = [];
+  if (scripts.typecheck) {
+    commands.push("npm run typecheck");
+  }
+  if (scripts.lint) {
+    commands.push("npm run lint");
+  }
+  if (scripts["format:check"]) {
+    commands.push("npm run format:check");
+  }
+  return commands;
+}
+
+export async function discoverLintCommands(cwd: string): Promise<string[]> {
+  const packageCommands = await packageLintCommands(cwd);
+  if (packageCommands.length > 0) {
+    return packageCommands;
+  }
+  const pyproject = await readIfExists(join(cwd, "pyproject.toml"));
+  if (pyproject) {
+    const commands: string[] = [];
+    if (pyproject.includes("ruff")) {
+      commands.push("ruff check .");
+    }
+    if (pyproject.includes("black")) {
+      commands.push("black --check .");
+    }
+    if (commands.length > 0) {
+      return commands;
+    }
+  }
+  if (await exists(join(cwd, "go.mod"))) {
+    return ["files=$(gofmt -l .) && test -z \"$files\" || { printf '%s\\n' \"$files\"; exit 1; }", "go vet ./..."];
+  }
+  if (await exists(join(cwd, "Cargo.toml"))) {
+    return ["cargo fmt --check", "cargo clippy"];
+  }
+  return [];
+}
+
+async function packageCoverageCommands(cwd: string): Promise<string[]> {
+  const parsed = await readPackageJson(cwd);
+  if (!parsed) {
+    return [];
+  }
+  const scripts = parsed.scripts ?? {};
+  if (scripts.coverage) {
+    return ["npm run coverage"];
+  }
+  const deps = { ...(parsed.dependencies ?? {}), ...(parsed.devDependencies ?? {}) };
+  const testScript = scripts.test ?? "";
+  const usesCoverageRunner = "jest" in deps || "vitest" in deps || testScript.includes("jest") || testScript.includes("vitest");
+  if (scripts.test && usesCoverageRunner) {
+    return ["npm test -- --coverage"];
+  }
+  return [];
+}
+
+export async function discoverCoverageCommands(cwd: string): Promise<string[]> {
+  const packageCommands = await packageCoverageCommands(cwd);
+  if (packageCommands.length > 0) {
+    return packageCommands;
+  }
+  const pyproject = await readIfExists(join(cwd, "pyproject.toml"));
+  if (pyproject && (pyproject.includes("[tool.pytest") || pyproject.includes("pytest"))) {
+    return ["python -m pytest --cov"];
+  }
+  if (await exists(join(cwd, "go.mod"))) {
+    return ["go test -cover ./..."];
+  }
+  return [];
+}

package/packages/core/src/version.ts

@@ -0,0 +1,2 @@
+export const DEVCREW_VERSION = "0.1.0";
+export const DEVCREW_NPM_PACKAGE = "@shenlee/devcrew";