@ifi/pi-spec 0.2.14

package/extension/prompts.ts

@@ -0,0 +1,124 @@
+import type { WorkflowPromptContext } from "./types.js";
+
+function formatChecklistBlock(checklists: WorkflowPromptContext["checklists"]): string[] {
+	if (!checklists || checklists.length === 0) {
+		return ["- No checklist files found."];
+	}
+	return checklists.map((checklist) => {
+		const status = checklist.incomplete === 0 ? "PASS" : "FAIL";
+		return `- ${checklist.name}: ${status} (${checklist.completed}/${checklist.total} complete, ${checklist.incomplete} incomplete) — ${checklist.path}`;
+	});
+}
+
+export function buildWorkflowPrompt(context: WorkflowPromptContext): string {
+	const lines = [
+		`You are executing the native /spec ${context.step} workflow inside pi.`,
+		"",
+		"## Native runtime notes",
+		"- Do NOT run any shell or PowerShell scripts referenced by the workflow template.",
+		"- Do NOT rely on the external spec-kit CLI. This pi extension has already prepared the local workspace and resolved the relevant paths.",
+		"- Treat any `/speckit.<name>` references in the workflow template as the equivalent `/spec <name>` step.",
+		"- Use pi's built-in tools directly to read, edit, write, grep, find, and run validation commands.",
+		"- Use `.specify/memory/pi-agent.md` as the native pi replacement for agent-specific context files or update-agent-context scripts.",
+		"",
+		"## Prepared workspace",
+		`- Repository root: ${context.paths.repoRoot}`,
+		`- Current branch: ${context.currentBranch}`,
+		`- Workflow template to follow: ${context.workflowTemplatePath}`,
+		`- Workflow README: ${context.paths.workflowReadmeFile}`,
+		`- Template directory: ${context.paths.templatesDir}`,
+		`- Constitution file: ${context.paths.constitutionFile}`,
+		`- Pi agent context file: ${context.paths.agentContextFile}`,
+		`- Extensions config: ${context.paths.extensionsConfigFile}`,
+	];
+
+	if (context.paths.featureBranch) {
+		lines.push(`- Active feature branch/name: ${context.paths.featureBranch}`);
+	}
+	if (context.paths.featureDir) {
+		lines.push(`- Feature directory: ${context.paths.featureDir}`);
+	}
+	if (context.paths.featureSpec) {
+		lines.push(`- Feature spec: ${context.paths.featureSpec}`);
+	}
+	if (context.paths.planFile) {
+		lines.push(`- Implementation plan: ${context.paths.planFile}`);
+	}
+	if (context.paths.tasksFile) {
+		lines.push(`- Task list: ${context.paths.tasksFile}`);
+	}
+	if (context.paths.researchFile) {
+		lines.push(`- Research file: ${context.paths.researchFile}`);
+	}
+	if (context.paths.dataModelFile) {
+		lines.push(`- Data model: ${context.paths.dataModelFile}`);
+	}
+	if (context.paths.quickstartFile) {
+		lines.push(`- Quickstart: ${context.paths.quickstartFile}`);
+	}
+	if (context.paths.contractsDir) {
+		lines.push(`- Contracts directory: ${context.paths.contractsDir}`);
+	}
+	if (context.paths.checklistsDir) {
+		lines.push(`- Checklists directory: ${context.paths.checklistsDir}`);
+	}
+
+	if (context.stepNotes.length > 0) {
+		lines.push("", "## Step-specific notes", ...context.stepNotes.map((note) => `- ${note}`));
+	}
+
+	if (context.step === "implement") {
+		lines.push("", "## Checklist status", ...formatChecklistBlock(context.checklists));
+	}
+
+	lines.push(
+		"",
+		"## User input from the slash command",
+		context.input.trim() || "(none)",
+		"",
+		"## Execution instructions",
+		"1. Read the workflow template path listed above before making changes.",
+		"2. Substitute the prepared paths above anywhere the original template expects script output variables.",
+		"3. If the template references optional hooks in `.specify/extensions.yml`, inspect that file manually instead of expecting automatic shell execution.",
+		"4. Perform the work directly in this repository using pi tools and then summarize what changed, what remains, and the next recommended `/spec` command.",
+	);
+
+	return lines.join("\n");
+}
+
+export function getStepNotes(step: WorkflowPromptContext["step"]): string[] {
+	switch (step) {
+		case "constitution":
+			return [
+				"Keep the constitution in `.specify/memory/constitution.md` as the canonical governance file.",
+				"When propagating changes, prefer updating `.specify/templates/*` and `.specify/memory/pi-agent.md` over agent-specific script outputs.",
+			];
+		case "specify":
+			return [
+				"The native /spec runtime has already generated the feature number, branch name, feature directory, and spec scaffold.",
+				"Do not create a second feature branch or rerun any feature-creation shell scripts.",
+			];
+		case "clarify":
+			return [
+				"Ask at most five high-impact clarification questions and update the spec incrementally after each accepted answer.",
+			];
+		case "checklist":
+			return ["Generate checklist items that test requirement quality, not implementation behavior."];
+		case "plan":
+			return [
+				"The native /spec runtime has already scaffolded `plan.md` if it was missing.",
+				"Use `.specify/memory/pi-agent.md` as the pi-native output in place of agent-specific update scripts.",
+			];
+		case "tasks":
+			return [
+				"Organize tasks by independently testable user stories and preserve the strict checkbox format from the template.",
+			];
+		case "analyze":
+			return ["Keep the analysis strictly read-only; do not edit files during this step."];
+		case "implement":
+			return [
+				"Mark completed tasks as `[x]` in tasks.md as you implement them.",
+				"If checklists are incomplete, respect the user's decision about whether to proceed.",
+			];
+	}
+}

package/extension/scaffold.ts

@@ -0,0 +1,151 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { WorkflowPaths } from "./types.js";
+
+const WORKFLOW_README = `# Native /spec Workflow
+
+This project uses the native pi spec workflow inspired by GitHub spec-kit.
+
+## Core commands
+
+- /spec init
+- /spec constitution <principles>
+- /spec specify <feature description>
+- /spec clarify [focus]
+- /spec checklist [domain]
+- /spec plan <technical context>
+- /spec tasks [context]
+- /spec analyze [focus]
+- /spec implement [focus]
+- /spec status
+- /spec next
+
+## Runtime notes
+
+- The pi extension handles feature numbering, branch naming, path resolution, and file scaffolding in TypeScript.
+- Workflow templates live in .specify/templates/commands/ and can be customized per project.
+- File templates live in .specify/templates/.
+- The native replacement for agent-specific context files is .specify/memory/pi-agent.md.
+- Feature artifacts live in specs/###-feature-name/.
+`;
+
+const DEFAULT_EXTENSIONS_YML = `settings:
+  auto_execute_hooks: true
+hooks: {}
+`;
+
+function getExtensionRoot(): string {
+	return path.dirname(fileURLToPath(import.meta.url));
+}
+
+function getBundledTemplatesRoot(): string {
+	return path.join(getExtensionRoot(), "assets", "templates");
+}
+
+function ensureDir(dir: string): void {
+	mkdirSync(dir, { recursive: true });
+}
+
+function copyDirIfMissing(sourceDir: string, targetDir: string): void {
+	ensureDir(targetDir);
+	for (const entry of readdirSync(sourceDir)) {
+		const sourcePath = path.join(sourceDir, entry);
+		const targetPath = path.join(targetDir, entry);
+		const sourceStat = statSync(sourcePath);
+		if (sourceStat.isDirectory()) {
+			copyDirIfMissing(sourcePath, targetPath);
+			continue;
+		}
+		if (!existsSync(targetPath)) {
+			copyFileSync(sourcePath, targetPath);
+		}
+	}
+}
+
+export function ensureWorkflowScaffold(paths: WorkflowPaths): string[] {
+	const created: string[] = [];
+	ensureDir(paths.specifyDir);
+	ensureDir(paths.specsDir);
+	ensureDir(paths.templatesDir);
+	ensureDir(paths.memoryDir);
+
+	const beforeTemplates = new Set<string>();
+	if (existsSync(paths.templatesDir)) {
+		for (const entry of readdirSync(paths.templatesDir)) {
+			beforeTemplates.add(entry);
+		}
+	}
+
+	copyDirIfMissing(getBundledTemplatesRoot(), paths.templatesDir);
+
+	for (const entry of readdirSync(paths.templatesDir)) {
+		if (!beforeTemplates.has(entry)) {
+			created.push(path.join(paths.templatesDir, entry));
+		}
+	}
+
+	if (!existsSync(paths.workflowReadmeFile)) {
+		writeFileSync(paths.workflowReadmeFile, WORKFLOW_README, "utf8");
+		created.push(paths.workflowReadmeFile);
+	}
+	if (!existsSync(paths.extensionsConfigFile)) {
+		writeFileSync(paths.extensionsConfigFile, DEFAULT_EXTENSIONS_YML, "utf8");
+		created.push(paths.extensionsConfigFile);
+	}
+	if (!existsSync(paths.constitutionFile)) {
+		const template = readFileSync(path.join(paths.templatesDir, "constitution-template.md"), "utf8");
+		writeFileSync(paths.constitutionFile, template, "utf8");
+		created.push(paths.constitutionFile);
+	}
+	if (!existsSync(paths.agentContextFile)) {
+		const template = readFileSync(path.join(paths.templatesDir, "agent-file-template.md"), "utf8");
+		writeFileSync(paths.agentContextFile, template, "utf8");
+		created.push(paths.agentContextFile);
+	}
+
+	return created;
+}
+
+export function ensureFeatureArtifacts(paths: WorkflowPaths): string[] {
+	if (!(paths.featureDir && paths.featureSpec && paths.checklistsDir)) {
+		return [];
+	}
+
+	const created: string[] = [];
+	ensureDir(paths.featureDir);
+	ensureDir(paths.checklistsDir);
+	if (!existsSync(paths.featureSpec)) {
+		const template = readFileSync(path.join(paths.templatesDir, "spec-template.md"), "utf8");
+		writeFileSync(paths.featureSpec, template, "utf8");
+		created.push(paths.featureSpec);
+	}
+	return created;
+}
+
+export function ensurePlanArtifact(paths: WorkflowPaths): string[] {
+	if (!(paths.featureDir && paths.planFile && paths.contractsDir)) {
+		return [];
+	}
+
+	const created: string[] = [];
+	ensureDir(paths.featureDir);
+	ensureDir(paths.contractsDir);
+	if (!existsSync(paths.planFile)) {
+		const template = readFileSync(path.join(paths.templatesDir, "plan-template.md"), "utf8");
+		writeFileSync(paths.planFile, template, "utf8");
+		created.push(paths.planFile);
+	}
+	return created;
+}
+
+export function getWorkflowTemplatePath(paths: WorkflowPaths, name: string): string {
+	return path.join(paths.templatesDir, "commands", `${name}.md`);
+}
+
+export function formatCreatedFiles(created: string[]): string {
+	if (created.length === 0) {
+		return "No new scaffold files were needed.";
+	}
+	return `Created ${created.length} scaffold file(s):\n${created.map((file) => `- ${file}`).join("\n")}`;
+}

package/extension/status.ts

@@ -0,0 +1,231 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import type { ChecklistSummary, WorkflowPaths, WorkflowStatus } from "./types.js";
+import { getLatestFeatureDir, listFeatureDirs } from "./workspace.js";
+
+function countChecklistItems(content: string): { total: number; completed: number; incomplete: number } {
+	const lines = content.split(/\r?\n/);
+	let total = 0;
+	let completed = 0;
+	let incomplete = 0;
+	for (const line of lines) {
+		if (/^- \[(?: |x|X)\]/.test(line)) {
+			total++;
+			if (/^- \[(?:x|X)\]/.test(line)) {
+				completed++;
+			} else {
+				incomplete++;
+			}
+		}
+	}
+	return { total, completed, incomplete };
+}
+
+export function summarizeChecklists(checklistsDir?: string): ChecklistSummary[] {
+	if (!(checklistsDir && existsSync(checklistsDir))) {
+		return [];
+	}
+
+	return readdirSync(checklistsDir)
+		.filter((entry) => entry.endsWith(".md"))
+		.map((entry) => {
+			const fullPath = path.join(checklistsDir, entry);
+			const content = readFileSync(fullPath, "utf8");
+			const counts = countChecklistItems(content);
+			return {
+				name: entry,
+				path: fullPath,
+				...counts,
+				status: counts.incomplete === 0 ? "pass" : "fail",
+			} satisfies ChecklistSummary;
+		})
+		.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function nextStepsFor(paths: WorkflowPaths, initialized: boolean): string[] {
+	if (!initialized) {
+		return ["/spec init", "/spec constitution <principles>", "/spec specify <feature description>"];
+	}
+
+	if (!(paths.featureDir && paths.featureSpec)) {
+		return ["/spec specify <feature description>", "/spec list"];
+	}
+
+	const steps: string[] = [];
+	const specExists = existsSync(paths.featureSpec);
+	const planExists = !!paths.planFile && existsSync(paths.planFile);
+	const tasksExist = !!paths.tasksFile && existsSync(paths.tasksFile);
+	const checklists = summarizeChecklists(paths.checklistsDir);
+	const hasIncompleteChecklist = checklists.some((checklist) => checklist.incomplete > 0);
+
+	if (!specExists) {
+		steps.push("/spec specify <feature description>");
+		return steps;
+	}
+
+	steps.push("/spec clarify");
+	steps.push("/spec checklist quality");
+
+	if (!planExists) {
+		steps.push("/spec plan <technical context>");
+		return steps;
+	}
+
+	if (!tasksExist) {
+		steps.push("/spec tasks");
+		return steps;
+	}
+
+	steps.push("/spec analyze");
+	steps.push(hasIncompleteChecklist ? "/spec implement (after checklist review)" : "/spec implement");
+	return steps;
+}
+
+export function buildWorkflowStatus(options: {
+	repoRoot: string;
+	currentBranch: string;
+	paths: WorkflowPaths;
+	activeFeature?: string;
+}): WorkflowStatus {
+	const featureDirs = listFeatureDirs(options.repoRoot);
+	const activeFeature = options.activeFeature ?? getLatestFeatureDir(options.repoRoot);
+	const initialized = existsSync(options.paths.specifyDir);
+	const artifacts = [
+		{
+			label: ".specify/README.md",
+			path: options.paths.workflowReadmeFile,
+			exists: existsSync(options.paths.workflowReadmeFile),
+		},
+		{
+			label: "constitution.md",
+			path: options.paths.constitutionFile,
+			exists: existsSync(options.paths.constitutionFile),
+		},
+		{ label: "pi-agent.md", path: options.paths.agentContextFile, exists: existsSync(options.paths.agentContextFile) },
+		{
+			label: "extensions.yml",
+			path: options.paths.extensionsConfigFile,
+			exists: existsSync(options.paths.extensionsConfigFile),
+		},
+	];
+
+	if (options.paths.featureSpec) {
+		artifacts.push({
+			label: "spec.md",
+			path: options.paths.featureSpec,
+			exists: existsSync(options.paths.featureSpec),
+		});
+	}
+	if (options.paths.planFile) {
+		artifacts.push({ label: "plan.md", path: options.paths.planFile, exists: existsSync(options.paths.planFile) });
+	}
+	if (options.paths.tasksFile) {
+		artifacts.push({ label: "tasks.md", path: options.paths.tasksFile, exists: existsSync(options.paths.tasksFile) });
+	}
+	if (options.paths.researchFile) {
+		artifacts.push({
+			label: "research.md",
+			path: options.paths.researchFile,
+			exists: existsSync(options.paths.researchFile),
+		});
+	}
+	if (options.paths.dataModelFile) {
+		artifacts.push({
+			label: "data-model.md",
+			path: options.paths.dataModelFile,
+			exists: existsSync(options.paths.dataModelFile),
+		});
+	}
+	if (options.paths.quickstartFile) {
+		artifacts.push({
+			label: "quickstart.md",
+			path: options.paths.quickstartFile,
+			exists: existsSync(options.paths.quickstartFile),
+		});
+	}
+	if (options.paths.contractsDir) {
+		artifacts.push({
+			label: "contracts/",
+			path: options.paths.contractsDir,
+			exists: existsSync(options.paths.contractsDir) && statSync(options.paths.contractsDir).isDirectory(),
+		});
+	}
+
+	return {
+		initialized,
+		repoRoot: options.repoRoot,
+		currentBranch: options.currentBranch,
+		featureDirs,
+		activeFeature,
+		paths: options.paths,
+		artifacts,
+		checklists: summarizeChecklists(options.paths.checklistsDir),
+		nextSteps: nextStepsFor(options.paths, initialized),
+	};
+}
+
+export function formatWorkflowStatus(status: WorkflowStatus): string {
+	const lines = [
+		"# /spec workflow status",
+		"",
+		`- Repository root: ${status.repoRoot}`,
+		`- Initialized: ${status.initialized ? "yes" : "no"}`,
+		`- Current branch: ${status.currentBranch}`,
+		`- Active feature: ${status.activeFeature ?? "(none)"}`,
+		`- Known features: ${status.featureDirs.length > 0 ? status.featureDirs.join(", ") : "(none)"}`,
+		"",
+		"## Artifacts",
+	];
+
+	for (const artifact of status.artifacts) {
+		lines.push(`- ${artifact.exists ? "✅" : "⬜"} ${artifact.label} — ${artifact.path}`);
+	}
+
+	lines.push("", "## Checklist status");
+	if (status.checklists.length === 0) {
+		lines.push("- No checklist files found.");
+	} else {
+		for (const checklist of status.checklists) {
+			lines.push(
+				`- ${checklist.status === "pass" ? "✅" : "⚠️"} ${checklist.name}: ${checklist.completed}/${checklist.total} complete (${checklist.incomplete} incomplete)`,
+			);
+		}
+	}
+
+	lines.push("", "## Next steps");
+	for (const step of status.nextSteps) {
+		lines.push(`- ${step}`);
+	}
+	return lines.join("\n");
+}
+
+export function formatHelpReport(): string {
+	return [
+		"# Native /spec workflow",
+		"",
+		"Use `/spec` with one of these subcommands:",
+		"",
+		"- `/spec init` — scaffold `.specify/`, templates, and memory files",
+		"- `/spec constitution <principles>` — create or amend the project constitution",
+		"- `/spec specify <feature description>` — create a numbered feature branch and spec scaffold",
+		"- `/spec clarify [focus]` — resolve critical ambiguities in the active spec",
+		"- `/spec checklist [domain]` — generate a requirements-quality checklist",
+		"- `/spec plan <technical context>` — build the implementation plan and design artifacts",
+		"- `/spec tasks [context]` — derive an executable tasks.md ordered by user story",
+		"- `/spec analyze [focus]` — run a read-only cross-artifact consistency review",
+		"- `/spec implement [focus]` — execute the plan from tasks.md and mark completed tasks",
+		"- `/spec status` — show current workflow state",
+		"- `/spec next` — show the next recommended command",
+		"- `/spec list` — list all known feature directories",
+		"",
+		"Tip: `/spec` with no arguments shows the current workflow status.",
+	].join("\n");
+}
+
+export function formatFeatureList(repoRoot: string): string {
+	const features = listFeatureDirs(repoRoot);
+	if (features.length === 0) {
+		return "# Known features\n\n- No feature directories found yet.";
+	}
+	return `# Known features\n\n${features.map((feature) => `- ${feature}`).join("\n")}`;
+}

package/extension/types.ts

@@ -0,0 +1,93 @@
+export const SPEC_SUBCOMMANDS = [
+	"status",
+	"help",
+	"init",
+	"constitution",
+	"specify",
+	"clarify",
+	"checklist",
+	"plan",
+	"tasks",
+	"analyze",
+	"implement",
+	"list",
+	"next",
+] as const;
+
+export type SpecSubcommand = (typeof SPEC_SUBCOMMANDS)[number];
+
+export const WORKFLOW_STEPS = [
+	"constitution",
+	"specify",
+	"clarify",
+	"checklist",
+	"plan",
+	"tasks",
+	"analyze",
+	"implement",
+] as const;
+
+export type WorkflowStep = (typeof WORKFLOW_STEPS)[number];
+
+export interface WorkflowPaths {
+	repoRoot: string;
+	specsDir: string;
+	specifyDir: string;
+	templatesDir: string;
+	memoryDir: string;
+	constitutionFile: string;
+	agentContextFile: string;
+	extensionsConfigFile: string;
+	workflowReadmeFile: string;
+	featureDir?: string;
+	featureBranch?: string;
+	featureNumber?: string;
+	featureSpec?: string;
+	planFile?: string;
+	tasksFile?: string;
+	researchFile?: string;
+	dataModelFile?: string;
+	quickstartFile?: string;
+	contractsDir?: string;
+	checklistsDir?: string;
+}
+
+export interface WorkflowStatus {
+	initialized: boolean;
+	repoRoot: string;
+	currentBranch: string;
+	featureDirs: string[];
+	activeFeature?: string;
+	paths: WorkflowPaths;
+	artifacts: Array<{ label: string; path: string; exists: boolean }>;
+	checklists: ChecklistSummary[];
+	nextSteps: string[];
+}
+
+export interface ChecklistSummary {
+	name: string;
+	path: string;
+	total: number;
+	completed: number;
+	incomplete: number;
+	status: "pass" | "fail";
+}
+
+export interface PreparedFeature {
+	branchName: string;
+	featureNumber: string;
+	featureDir: string;
+	specFile: string;
+	checklistsDir: string;
+	createdBranch: boolean;
+}
+
+export interface WorkflowPromptContext {
+	step: WorkflowStep;
+	input: string;
+	paths: WorkflowPaths;
+	currentBranch: string;
+	workflowTemplatePath: string;
+	stepNotes: string[];
+	checklists?: ChecklistSummary[];
+}