stonecut 1.0.0

package/src/skills/stonecut-prd/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: stonecut-prd
+description: Write a PRD through structured user interview, codebase exploration, and module design. Saves the result as a local file or GitHub issue. Use when the user wants to create a product requirements document or plan a new feature.
+---
+
+You are writing a PRD as part of the Stonecut workflow. Follow these steps, skipping any that aren't necessary for the situation.
+
+## Process
+
+### 1. Gather context
+
+Ask the user for a detailed description of the problem they want to solve and any ideas they have for the solution.
+
+### 2. Explore the codebase
+
+Explore the repo to verify the user's assertions and understand the current state of the code.
+
+### 3. Interview
+
+Interview the user relentlessly about every aspect of the plan until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
+
+### 4. Design modules
+
+Sketch out the major modules that need to be built or modified. Look for opportunities to extract deep modules — modules that encapsulate significant functionality behind a simple, testable interface that rarely changes.
+
+Check with the user that these modules match their expectations. Ask which modules they want tests written for.
+
+### 5. Choose a destination
+
+Ask the user where to save the PRD:
+
+- **Local file** — Save as `.stonecut/<name>/prd.md` in the project. Ask the user: "What should I name this spec?" The name can be anything — a ticket ID (e.g., `ASC-1`), a descriptive slug (e.g., `auth-refactor`), or whatever fits. Create the `.stonecut/<name>/` directory if it doesn't exist.
+- **GitHub issue** — Create a GitHub issue using `gh issue create --label prd`. Before creating, ensure the `prd` label exists:
+
+  ```bash
+  # Only create the label if it doesn't already exist
+  if ! gh label list --search "prd" --json name --jq '.[].name' | grep -qx "prd"; then
+    gh label create prd --description "Product Requirements Document" --color "0052CC"
+  fi
+  ```
+
+If the project already has a `.stonecut/` directory, default to suggesting local. Otherwise, just ask.
+
+### 6. Documentation impact check
+
+Before writing the PRD, ensure that documentation impact has been explicitly addressed. Based on everything you've learned from the interview and codebase exploration, analyze which user-facing documentation artifacts (README, CLI help text, docs/ content) would be affected by these changes.
+
+Present your assessment to the user for confirmation:
+
+- If changes are needed, list the specific artifacts and what would need updating.
+- If no changes are needed, state why (e.g., "Internal refactor — no user-facing behavior changes") and ask the user to confirm.
+
+Record the confirmed answer for inclusion in the PRD's Documentation Impact section.
+
+This step is a gate — do not proceed to writing the PRD until documentation impact is resolved.
+
+### 7. Write the PRD
+
+Once you have a complete understanding of the problem and solution, write the PRD using the template below and save it to the chosen destination.
+
+<prd-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Documentation Impact
+
+Which user-facing documentation artifacts are affected by these changes:
+
+- **README** — Which sections need adding or updating?
+- **CLI help text** — Are commands, flags, or usage examples changing?
+- **docs/ content** — Are there deeper documentation files that need updating?
+
+If no documentation changes are needed, state why (e.g., "Internal refactor — no user-facing behavior changes"). This assessment should be provided by the model based on its analysis and confirmed by the user during the interview.
+
+## Out of Scope
+
+A description of the things that are out of scope for this PRD.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</prd-template>
+
+## Next Step
+
+Once the PRD is saved, ask the user: "Ready to break this into issues? I can run `/stonecut-issues` next."

package/src/skills.ts

@@ -0,0 +1,163 @@
+/**
+ * Skills management — setup and removal of Claude Code skill symlinks.
+ *
+ * Exports pure functions; CLI integration is in cli.ts.
+ */
+
+import {
+	existsSync,
+	lstatSync,
+	statSync,
+	mkdirSync,
+	readlinkSync,
+	realpathSync,
+	symlinkSync,
+	unlinkSync,
+} from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+export const SKILL_NAMES = ["stonecut-interview", "stonecut-prd", "stonecut-issues"];
+
+/**
+ * Return the path to the skills/ directory shipped with this package.
+ */
+export function getSkillsSourceDir(): string {
+	return resolve(import.meta.dir, "skills");
+}
+
+/**
+ * Return the skills target directory, optionally creating it.
+ */
+export function getSkillsTargetDir(
+	opts: {
+		create?: boolean;
+		claudeRoot?: string;
+	} = {},
+): string {
+	const { create = true, claudeRoot } = opts;
+	const target = claudeRoot ? join(claudeRoot, "skills") : join(homedir(), ".claude", "skills");
+	if (create) {
+		mkdirSync(target, { recursive: true });
+	}
+	return target;
+}
+
+/** Check if path exists as a symlink (without following it). */
+function isSymlink(path: string): boolean {
+	try {
+		return lstatSync(path).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+
+/** Check if something exists at path (symlink or real). */
+function pathExists(path: string): boolean {
+	// existsSync follows symlinks, so also check lstat for dangling symlinks
+	if (existsSync(path)) return true;
+	return isSymlink(path);
+}
+
+export interface SkillsOutput {
+	messages: string[];
+	warnings: string[];
+}
+
+/**
+ * Install Stonecut skills as symlinks into the target skills directory.
+ */
+export function setupSkills(claudeRoot?: string): SkillsOutput {
+	const sourceDir = getSkillsSourceDir();
+	const output: SkillsOutput = { messages: [], warnings: [] };
+
+	if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory()) {
+		throw new Error(`Skills directory not found at ${sourceDir}`);
+	}
+
+	const targetDir = getSkillsTargetDir({ claudeRoot });
+
+	for (const name of SKILL_NAMES) {
+		const source = join(sourceDir, name);
+		const target = join(targetDir, name);
+
+		if (!existsSync(source) || !statSync(source).isDirectory()) {
+			output.warnings.push(`Warning: skill source not found: ${source}`);
+			continue;
+		}
+
+		if (isSymlink(target)) {
+			try {
+				const existing = realpathSync(target);
+				if (existing === realpathSync(source)) {
+					// Already points to the right place — skip silently
+					continue;
+				}
+			} catch {
+				// Dangling symlink — remove it and re-create below
+				unlinkSync(target);
+				symlinkSync(source, target);
+				output.messages.push(`Replaced dangling link ${name} -> ${source}`);
+				continue;
+			}
+			const linkTarget = readlinkSync(target);
+			output.warnings.push(
+				`Warning: ${target} already exists as symlink -> ${linkTarget}. Skipping.`,
+			);
+			continue;
+		}
+
+		if (pathExists(target)) {
+			// Regular file or directory
+			output.warnings.push(`Warning: ${target} already exists (not a symlink). Skipping.`);
+			continue;
+		}
+
+		symlinkSync(source, target);
+		output.messages.push(`Linked ${name} -> ${source}`);
+	}
+
+	return output;
+}
+
+/**
+ * Remove Stonecut skill symlinks from the target skills directory.
+ */
+export function removeSkills(claudeRoot?: string): SkillsOutput {
+	const sourceDir = getSkillsSourceDir();
+	const targetDir = getSkillsTargetDir({ create: false, claudeRoot });
+	const output: SkillsOutput = { messages: [], warnings: [] };
+
+	if (!existsSync(targetDir) || !statSync(targetDir).isDirectory()) {
+		return output;
+	}
+
+	for (const name of SKILL_NAMES) {
+		const target = join(targetDir, name);
+
+		if (!isSymlink(target)) {
+			continue;
+		}
+
+		// Only remove if it points into the Stonecut package
+		let resolved: string;
+		try {
+			resolved = realpathSync(target);
+		} catch {
+			// Dangling symlink — safe to remove
+			unlinkSync(target);
+			output.messages.push(`Removed dangling link ${name}`);
+			continue;
+		}
+
+		const expectedPath = join(sourceDir, name);
+		if (!existsSync(expectedPath) || resolved !== realpathSync(expectedPath)) {
+			continue;
+		}
+
+		unlinkSync(target);
+		output.messages.push(`Removed ${name}`);
+	}
+
+	return output;
+}

package/src/templates/execute.md

@@ -0,0 +1,28 @@
+You are executing a single task from {task_source}.
+
+## Instructions
+
+1. Read the PRD below — it contains the full context, architecture, and constraints.
+2. Read the issue spec below — it contains exactly what to build and the acceptance criteria.
+3. Implement everything described in the issue spec.
+4. Verify your work compiles and passes any validation described in the issue.
+5. Ensure `.gitignore` is updated for any generated artifacts (build outputs, dependencies, etc.).
+
+IMPORTANT:
+
+- Do ONLY this one issue. Stop after verifying.
+- Do NOT commit — the orchestrator handles git operations.
+- Do NOT modify files outside the scope of this issue unless fixing an import path that changed.
+- Scope lint to specific files — do not run project-wide lint that auto-fixes unrelated files.
+
+---
+
+## PRD
+
+{prd_content}
+
+---
+
+## Issue {issue_number}: {issue_filename}
+
+{issue_content}

package/src/types.ts

@@ -0,0 +1,83 @@
+/**
+ * Core types and interfaces shared across the Stonecut CLI.
+ */
+
+/** Structured result from a single runner execution. */
+export interface RunResult {
+	success: boolean;
+	exitCode: number;
+	durationSeconds: number;
+	output?: string;
+	error?: string;
+}
+
+/** Result of a single afk iteration. */
+export interface IterationResult {
+	issueNumber: number;
+	issueFilename: string;
+	success: boolean;
+	elapsedSeconds: number;
+	error?: string;
+}
+
+/** Protocol that all runner adapters must satisfy. */
+export interface Runner {
+	run(prompt: string): Promise<RunResult>;
+}
+
+/** Snapshot of the working tree state before a runner session. */
+export interface WorkingTreeSnapshot {
+	untracked: Set<string>;
+}
+
+/** Git operations used by the runner loop, injectable for testing. */
+export interface GitOps {
+	snapshotWorkingTree(): WorkingTreeSnapshot;
+	stageChanges(snapshot: WorkingTreeSnapshot): boolean;
+	commitChanges(message: string): [boolean, string];
+	revertUncommitted(snapshot: WorkingTreeSnapshot): void;
+}
+
+/** A single issue from a local spec. */
+export interface Issue {
+	number: number;
+	filename: string;
+	path: string;
+	content: string;
+}
+
+/** Structured metadata for a GitHub-backed PRD issue. */
+export interface GitHubPrd {
+	number: number;
+	title: string;
+	body: string;
+}
+
+/** A single sub-issue from a GitHub PRD. */
+export interface GitHubIssue {
+	number: number;
+	title: string;
+	body: string;
+}
+
+/** Source interface for reading issues from any backend (local or GitHub). */
+export interface Source<T> {
+	getNextIssue(): Promise<T | null>;
+	completeIssue(issue: T): Promise<void>;
+	getRemainingCount(): Promise<[number, number]>;
+	getPrdContent(): Promise<string>;
+}
+
+/** Logger interface for session-scoped logging. */
+export interface LogWriter {
+	log(message: string): void;
+	close(): void;
+}
+
+/** Session context threaded through a stonecut run. */
+export interface Session {
+	logger: LogWriter;
+	git: GitOps;
+	runner: Runner;
+	runnerName: string;
+}