stonecut 1.2.0 → 1.3.0

package/src/skills/stonecut-review-architecture/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: stonecut-review-architecture
+description: Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable.
+---
+
+# Review Architecture
+
+Explore a codebase like an AI would, surface architectural friction, discover opportunities for improving testability, and propose module-deepening refactors.
+
+A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside.
+
+## Process
+
+### 1. Explore the codebase
+
+Use the Agent tool with subagent_type=Explore to navigate the codebase naturally. Do NOT follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small files?
+- Where are modules so shallow that the interface is nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
+- Where do tightly-coupled modules create integration risk in the seams between them?
+- Which parts of the codebase are untested, or hard to test?
+
+The friction you encounter IS the signal.
+
+### 2. Present candidates
+
+Present a numbered list of deepening opportunities. For each candidate, show:
+
+- **Cluster**: Which modules/concepts are involved
+- **Why they're coupled**: Shared types, call patterns, co-ownership of a concept
+- **Dependency category**: See [REFERENCE.md](REFERENCE.md) for the four categories
+- **Test impact**: What existing tests would be replaced by boundary tests
+
+Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
+
+### 3. User picks a candidate
+
+### 4. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would need to rely on
+- A rough illustrative code sketch to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 5.
+
+### 5. Design multiple interfaces
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category, what's being hidden). This brief is independent of the user-facing explanation in Step 4. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1-3 entry points max"
+- Agent 2: "Maximize flexibility — support many use cases and extension"
+- Agent 3: "Optimize for the most common caller — make the default case trivial"
+- Agent 4 (if applicable): "Design around the ports & adapters pattern for cross-boundary dependencies"
+
+Each sub-agent outputs:
+
+1. Interface signature (types, methods, params)
+2. Usage example showing how callers use it
+3. What complexity it hides internally
+4. Dependency strategy (how deps are handled — see [REFERENCE.md](REFERENCE.md))
+5. Trade-offs
+
+Present designs sequentially, then compare them in prose.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid.
+
+### 6. User picks an interface (or accepts recommendation)
+
+### 7. Choose a destination
+
+Ask the user where to save the RFC:
+
+- **Local file** — Save as `.stonecut/specs/<name>/rfc.md` in the project. Ask the user: "What should I name this spec?" Create the `.stonecut/specs/<name>/` directory if it doesn't exist.
+- **GitHub issue** — Create a GitHub issue using `gh issue create --label rfc`. Before creating, ensure the `rfc` label exists:
+
+  ```bash
+  # Only create the label if it doesn't already exist
+  if ! gh label list --search "rfc" --json name --jq '.[].name' | grep -qx "rfc"; then
+    gh label create rfc --description "Request for Comments — architecture/design decision" --color "D93F0B"
+  fi
+  ```
+
+If the project already has a `.stonecut/` directory, default to suggesting local. Otherwise, just ask.
+
+### 8. Write the RFC
+
+Use the template in [REFERENCE.md](REFERENCE.md). Do NOT ask the user to review before creating — just create it and share the result.
+
+The RFC captures design decisions — what was chosen, what was rejected, and why. The PRD writer (whether in this session or a future one) will explore the codebase itself; the RFC's job is to carry the decisions so they don't need to be re-derived. Leave implementation-level detail (exact signatures, migration steps, test file changes) for the PRD and issues.
+
+## Next Step
+
+Once the RFC is saved, ask the user: "Ready to write the PRD? I can run `/stonecut-prd` next."

package/src/skills.ts

@@ -17,7 +17,12 @@ import {
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
 
-export const SKILL_NAMES = ["stonecut-interview", "stonecut-prd", "stonecut-issues"];
+export const SKILL_NAMES = [
+	"stonecut-interview",
+	"stonecut-prd",
+	"stonecut-issues",
+	"stonecut-review-architecture",
+];
 
 /**
  * Return the path to the skills/ directory shipped with this package.

package/src/sources/github.ts

@@ -5,20 +5,9 @@
  * structured as a stateless SourceProvider.
  */
 
+import { runSync } from "../spawn";
 import type { IssueData, PrdData, PrdSummary, SourceProvider } from "./types.js";
 
-function runSync(cmd: string[]): { exitCode: number; stdout: string; stderr: string } {
-	const proc = Bun.spawnSync(cmd, {
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-	return {
-		exitCode: proc.exitCode,
-		stdout: proc.stdout.toString(),
-		stderr: proc.stderr.toString(),
-	};
-}
-
 export class GitHubSourceProvider implements SourceProvider {
 	readonly owner: string;
 	readonly repo: string;

package/src/spawn.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared synchronous process wrapper used by git.ts and sources/github.ts.
+ *
+ * Single source of truth for Bun.spawnSync stdout/stderr conversion.
+ */
+
+/** Run a command synchronously, optionally in a specific working directory. */
+export function runSync(
+	cmd: string[],
+	cwd?: string,
+): { exitCode: number; stdout: string; stderr: string } {
+	const proc = Bun.spawnSync(cmd, {
+		stdout: "pipe",
+		stderr: "pipe",
+		...(cwd && { cwd }),
+	});
+	return {
+		exitCode: proc.exitCode,
+		stdout: proc.stdout.toString(),
+		stderr: proc.stderr.toString(),
+	};
+}

package/src/sync-back.ts

@@ -0,0 +1,88 @@
+/**
+ * Sync-back — notify external sources when issues or PRDs complete.
+ *
+ * syncBackIssue: read frontmatter from an issue file, resolve provider, call onIssueComplete.
+ * syncBackPrd: read frontmatter from a PRD file, resolve provider, call onPrdComplete.
+ *
+ * Failures are logged as warnings but never thrown — sync-back is best-effort.
+ */
+
+import { readFileSync } from "fs";
+import { parseFrontmatter } from "./frontmatter";
+import { getSourceProvider } from "./sources/index";
+import type { LogWriter } from "./types";
+
+/**
+ * Configuration for syncing issue/PRD completion back to an external source.
+ *
+ * When provided to runAfkLoop, the runner reads frontmatter from completed
+ * issue files. If a `source` field is present, the corresponding provider
+ * is resolved and notified of the completion.
+ */
+export interface SyncBackConfig<T> {
+	/** Return the file path for a completed issue, or undefined to skip sync-back. */
+	getIssuePath: (issue: T) => string | undefined;
+	/** Path to the PRD file, used for sync-back after all issues complete. */
+	prdPath?: string;
+	/** Read a file's contents. Injectable for testing; defaults to fs.readFileSync. */
+	readFile?: (path: string) => string;
+	/** Resolve a source provider by name. Injectable for testing; defaults to getSourceProvider. */
+	resolveProvider?: (name: string) => {
+		onIssueComplete(id: string): Promise<void>;
+		onPrdComplete(id: string): Promise<void>;
+	};
+}
+
+/**
+ * Sync a completed issue back to its external source.
+ *
+ * Reads frontmatter from the issue file. If `source` and `issue` fields
+ * are present, resolves the provider and calls onIssueComplete.
+ * Failures are logged as warnings but never thrown.
+ */
+export async function syncBackIssue(
+	filePath: string,
+	logger: LogWriter,
+	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
+	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
+): Promise<void> {
+	try {
+		const content = readFile(filePath);
+		const { meta } = parseFrontmatter(content);
+		if (!meta.source || !meta.issue) return;
+
+		const provider = resolveProvider!(meta.source);
+		await provider.onIssueComplete(meta.issue);
+		logger.log(`Synced issue #${meta.issue} back to ${meta.source}`);
+	} catch (err: unknown) {
+		const message = err instanceof Error ? err.message : String(err);
+		logger.log(`Warning: sync-back failed for issue at ${filePath}: ${message}`);
+	}
+}
+
+/**
+ * Sync PRD completion back to its external source.
+ *
+ * Reads frontmatter from the PRD file. If `source` and `issue` fields
+ * are present, resolves the provider and calls onPrdComplete.
+ * Failures are logged as warnings but never thrown.
+ */
+export async function syncBackPrd(
+	filePath: string,
+	logger: LogWriter,
+	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
+	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
+): Promise<void> {
+	try {
+		const content = readFile(filePath);
+		const { meta } = parseFrontmatter(content);
+		if (!meta.source || !meta.issue) return;
+
+		const provider = resolveProvider!(meta.source);
+		await provider.onPrdComplete(meta.issue);
+		logger.log(`Synced PRD #${meta.issue} back to ${meta.source}`);
+	} catch (err: unknown) {
+		const message = err instanceof Error ? err.message : String(err);
+		logger.log(`Warning: sync-back failed for PRD at ${filePath}: ${message}`);
+	}
+}