stonecut 1.2.0 → 1.2.1

package/README.md

@@ -7,7 +7,9 @@ A CLI that drives PRD-driven development with agentic coding CLIs. You write the
 
 ## Workflow
 
-Ideas can come from anywhere — Jira tickets, Slack threads, MCP servers, or just a conversation. The pipeline starts once you're ready to act on one:
+Ideas can come from anywhere — Jira tickets, Slack threads, MCP servers, or just a conversation. The pipeline has two entry points depending on where work originates:
+
+**From a raw idea:** `roadmap issue → interview → PRD → issues → execute`
 
 1. **`/stonecut-interview`** — Stress-test the idea. Get grilled on the plan until it's solid.
 2. **`/stonecut-prd`** — Turn the validated idea into a PRD (local file or GitHub issue).
@@ -15,11 +17,15 @@ Ideas can come from anywhere — Jira tickets, Slack threads, MCP servers, or ju
 4. **`stonecut import`** _(optional)_ — If the PRD lives in GitHub, import it and its issues into `.stonecut/`.
 5. **`stonecut`** — Execute the issues sequentially with an agentic coding CLI.
 
+**From a technical exploration:** `RFC issue → PRD → issues → execute`
+
+Architecture decisions and refactoring plans that emerge from a technical investigation (e.g. a codebase review) skip the interview — the exploration itself produces the design decisions. Capture the outcome as an `rfc`-labeled GitHub issue, then write the PRD referencing it.
+
 Steps 1–3 are Claude Code skills installed via `stonecut setup-skills`. Steps 4–5 are the Stonecut CLI.
 
-### Suggested: managing your idea backlog
+### Suggested: managing your backlog
 
-For projects using GitHub issues, we recommend tracking ideas with a `roadmap` label. When an idea is ready, interview it, write the PRD (which closes the roadmap issue), break it into sub-issues, import with `stonecut import --github`, and execute. See [DESIGN.md](DESIGN.md#suggested-practice-managing-your-idea-backlog-with-github-labels) for the full flow.
+For projects using GitHub issues, we recommend tracking ideas with a `roadmap` label and architecture decisions with an `rfc` label. When an idea is ready, interview it, write the PRD (which closes the roadmap issue), break it into sub-issues, import with `stonecut import --github`, and execute. See [DESIGN.md](DESIGN.md#entry-points) for the full flow.
 
 ## Installation
 
@@ -342,13 +348,13 @@ To add a new source provider (e.g. Jira, Linear):
 
 ## Skills
 
-The repo ships three Claude Code skills for steps 1–3 of the workflow. Install them with:
+The repo ships four Claude Code skills for the workflow. Install them with:
 
 ```sh
 stonecut setup-skills
 ```
 
-This creates symlinks in `~/.claude/skills/` pointing to the installed package. Once linked, they're available as `/stonecut-interview`, `/stonecut-prd`, and `/stonecut-issues` in any Claude Code session.
+This creates symlinks in `~/.claude/skills/` pointing to the installed package. Once linked, they're available as `/stonecut-interview`, `/stonecut-prd`, `/stonecut-issues`, and `/stonecut-review-architecture` in any Claude Code session.
 
 For non-default Claude Code installations, pass `--target` with the Claude root path:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonecut",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "CLI that drives PRD-driven development with agentic coding CLIs",
   "license": "MIT",
   "repository": {

package/src/cli.ts

@@ -86,7 +86,7 @@ export interface LocalPrdEntry {
  * Scan .stonecut subdirectories for directories containing prd.md and compute
  * completion counts from status.json.
  */
-export function scanLocalPrds(baseDir: string = ".stonecut"): LocalPrdEntry[] {
+export function scanLocalPrds(baseDir: string = ".stonecut/prd"): LocalPrdEntry[] {
 	if (!existsSync(baseDir)) return [];
 
 	const entries: LocalPrdEntry[] = [];
@@ -240,8 +240,6 @@ export async function preExecution(
 	suggestedBranch: string,
 	prefilled?: { branch?: string; baseBranch?: string },
 ): Promise<[string, string]> {
-	ensureCleanTree();
-
 	let branch: string;
 	if (prefilled?.branch) {
 		branch = prefilled.branch;
@@ -380,10 +378,12 @@ export function buildProgram(): Command {
 	program
 		.command("run", { isDefault: true })
 		.description("Execute issues from a local PRD.")
-		.option("--local <name>", "Local PRD name (.stonecut/<name>/)")
+		.option("--local <name>", "Local PRD name (.stonecut/prd/<name>/)")
 		.option("-i, --iterations <value>", "Number of issues to process, or 'all'")
 		.option("--runner <name>", "Agentic CLI runner (claude, codex)")
 		.action(async (opts) => {
+			ensureCleanTree();
+
 			const config = loadConfig();
 
 			const validated = validateRunSource(opts.local);

package/src/import.ts

@@ -37,7 +37,7 @@ export async function importSpec(options: ImportOptions): Promise<ImportResult>
 		throw new Error("Could not derive a spec name from the PRD title. Use --name to specify one.");
 	}
 
-	const specDir = join(".stonecut", specName);
+	const specDir = join(".stonecut", "prd", specName);
 
 	if (existsSync(specDir)) {
 		if (!options.force) {

package/src/local.ts

@@ -1,4 +1,4 @@
-/** Local spec source — reads issues from .stonecut/<name>/. */
+/** Local spec source — reads issues from .stonecut/prd/<name>/. */
 
 import { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, statSync } from "fs";
 import { join } from "path";
@@ -11,7 +11,7 @@ export class LocalSource implements Source<Issue> {
 
 	constructor(name: string) {
 		this.name = name;
-		this.specDir = join(".stonecut", name);
+		this.specDir = join(".stonecut", "prd", name);
 		this.validate();
 	}
 

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

@@ -0,0 +1,109 @@
+# Reference
+
+## Dependency Categories
+
+When assessing a candidate for deepening, classify its dependencies:
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — just merge the modules and test directly.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (e.g., PGLite for Postgres, in-memory filesystem). Deepenable if the test substitute exists. The deepened module is tested with the local stand-in running in the test suite.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a port (interface) at the module boundary. The deep module owns the logic; the transport is injected. Tests use an in-memory adapter. Production uses the real HTTP/gRPC/queue adapter.
+
+Recommendation shape: "Define a shared interface (port), implement an HTTP adapter for production and an in-memory adapter for testing, so the logic can be tested as one deep module even though it's deployed across a network boundary."
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. Mock at the boundary. The deepened module takes the external dependency as an injected port, and tests provide a mock implementation.
+
+## Testing Strategy
+
+The core principle: **replace, don't layer.**
+
+- Old unit tests on shallow modules are waste once boundary tests exist — delete them
+- Write new tests at the deepened module's interface boundary
+- Tests assert on observable outcomes through the public interface, not internal state
+- Tests should survive internal refactors — they describe behavior, not implementation
+
+## RFC Template
+
+<rfc-template>
+
+## Context
+
+Why this exploration was initiated:
+
+- What motivated the review (e.g., preparing for new features, observable friction, scaling concerns)
+- What areas of the codebase were explored
+- High-level findings from the exploration
+
+## Constraints
+
+Non-negotiable rules that narrow the solution space:
+
+- Architectural invariants that must be preserved
+- Backward compatibility requirements
+- Testing or deployment constraints
+
+## Problem
+
+Describe the architectural friction:
+
+- Which modules are shallow and tightly coupled
+- What integration risk exists in the seams between them
+- Why this makes the codebase harder to navigate and maintain
+
+## Alternatives Considered
+
+For each design explored during the multi-agent step:
+
+- **Design name** — One-line summary of the approach
+- Key trade-offs: what it gains, what it loses
+- Why it was accepted, rejected, or partially adopted
+
+Include a comparison (table or prose) so the reader can see why the chosen design won.
+
+## Proposed Design
+
+The chosen design. For each new or modified module:
+
+- What the module owns (responsibilities)
+- What it hides (implementation details callers don't see)
+- What it exposes (the public surface area — described, not full signatures)
+- Dependency graph between modules (which depends on which, and why)
+
+## Dependency Strategy
+
+Which category applies and how dependencies are handled:
+
+- **In-process**: merged directly
+- **Local-substitutable**: tested with [specific stand-in]
+- **Ports & adapters**: port definition, production adapter, test adapter
+- **Mock**: mock boundary for external services
+
+## Testing Impact
+
+High-level testing implications of the design:
+
+- What new boundary tests the design enables
+- What existing test patterns become redundant
+- Any test infrastructure changes needed
+
+## Implementation Guidance
+
+Durable architectural guidance — the _what and why_, not the _how_:
+
+- What the module should own (responsibilities)
+- What it should hide (implementation details)
+- What it should expose (the interface contract)
+- Key invariants the implementation must preserve
+
+Do NOT include specific file-level migration steps, exact function signatures, or line-by-line changes. Those belong in the PRD and issues.
+
+</rfc-template>

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/<name>/rfc.md` in the project. Ask the user: "What should I name this spec?" Create the `.stonecut/<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.