@ifi/pi-spec 0.2.14

package/extension/assets/templates/tasks-template.md

@@ -0,0 +1,251 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+  
+  The /speckit.tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+  
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+  
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

package/extension/git.ts

@@ -0,0 +1,64 @@
+import { execFileSync } from "node:child_process";
+
+export interface GitClient {
+	getRepoRoot(cwd: string): string | null;
+	getCurrentBranch(repoRoot: string): string | null;
+	listBranches(repoRoot: string): string[];
+	isDirty(repoRoot: string): boolean;
+	createAndSwitchBranch(repoRoot: string, branchName: string): void;
+}
+
+function runGit(repoRoot: string, args: string[]): string {
+	return execFileSync("git", args, {
+		cwd: repoRoot,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+	}).trim();
+}
+
+export function createGitClient(): GitClient {
+	return {
+		getRepoRoot(cwd) {
+			try {
+				const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+					cwd,
+					encoding: "utf8",
+					stdio: ["ignore", "pipe", "ignore"],
+				}).trim();
+				return root || null;
+			} catch {
+				return null;
+			}
+		},
+		getCurrentBranch(repoRoot) {
+			try {
+				const branch = runGit(repoRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
+				return branch || null;
+			} catch {
+				return null;
+			}
+		},
+		listBranches(repoRoot) {
+			try {
+				const output = runGit(repoRoot, ["for-each-ref", "--format=%(refname:short)", "refs/heads", "refs/remotes"]);
+				return output
+					.split(/\r?\n/)
+					.map((line) => line.trim())
+					.filter(Boolean)
+					.map((line) => line.replace(/^[^/]+\//, ""));
+			} catch {
+				return [];
+			}
+		},
+		isDirty(repoRoot) {
+			try {
+				return runGit(repoRoot, ["status", "--short"]).length > 0;
+			} catch {
+				return false;
+			}
+		},
+		createAndSwitchBranch(repoRoot, branchName) {
+			runGit(repoRoot, ["checkout", "-b", branchName]);
+		},
+	};
+}

package/extension/index.ts

@@ -0,0 +1,366 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { createGitClient } from "./git.js";
+import { buildWorkflowPrompt, getStepNotes } from "./prompts.js";
+import {
+	ensureFeatureArtifacts,
+	ensurePlanArtifact,
+	ensureWorkflowScaffold,
+	formatCreatedFiles,
+	getWorkflowTemplatePath,
+} from "./scaffold.js";
+import {
+	buildWorkflowStatus,
+	formatFeatureList,
+	formatHelpReport,
+	formatWorkflowStatus,
+	summarizeChecklists,
+} from "./status.js";
+import { SPEC_SUBCOMMANDS, type SpecSubcommand, type WorkflowPaths, type WorkflowStep } from "./types.js";
+import {
+	buildWorkflowPaths,
+	findRepoRoot,
+	getLatestFeatureDir,
+	listFeatureDirs,
+	prepareFeatureWorkspace,
+	resolveFeatureFromBranch,
+} from "./workspace.js";
+
+const REPORT_MESSAGE_TYPE = "pi-spec-report";
+const PROMPT_OPTIONAL_STEPS = new Set<WorkflowStep>(["clarify", "tasks", "analyze", "implement"]);
+
+function tokenize(input: string): { subcommand: SpecSubcommand | null; remainder: string } {
+	const trimmed = input.trim();
+	if (!trimmed) {
+		return { subcommand: "status", remainder: "" };
+	}
+	const [raw, ...rest] = trimmed.split(/\s+/);
+	const normalized = raw.toLowerCase();
+	if ((SPEC_SUBCOMMANDS as readonly string[]).includes(normalized)) {
+		return { subcommand: normalized as SpecSubcommand, remainder: rest.join(" ").trim() };
+	}
+	return { subcommand: null, remainder: trimmed };
+}
+
+function sendReport(pi: ExtensionAPI, content: string): void {
+	pi.sendMessage({ customType: REPORT_MESSAGE_TYPE, content, display: true });
+}
+
+function isWorkflowStep(subcommand: SpecSubcommand): subcommand is WorkflowStep {
+	return ["constitution", "specify", "clarify", "checklist", "plan", "tasks", "analyze", "implement"].includes(
+		subcommand,
+	);
+}
+
+async function promptForMissingInput(
+	ctx: ExtensionCommandContext,
+	title: string,
+	placeholder: string,
+): Promise<string | undefined> {
+	if (!ctx.hasUI) {
+		return undefined;
+	}
+	if (typeof ctx.ui.editor === "function") {
+		const response = await ctx.ui.editor(title, placeholder);
+		return response?.trim() || undefined;
+	}
+	if (typeof ctx.ui.input === "function") {
+		const response = await ctx.ui.input(title, placeholder);
+		return response?.trim() || undefined;
+	}
+	return undefined;
+}
+
+function stepNeedsRequiredInput(step: WorkflowStep): boolean {
+	return !PROMPT_OPTIONAL_STEPS.has(step);
+}
+
+async function resolveActiveFeatureName(
+	ctx: ExtensionCommandContext,
+	repoRoot: string,
+	currentBranch: string,
+): Promise<string | undefined> {
+	const featureFromBranch = resolveFeatureFromBranch(repoRoot, currentBranch);
+	if (featureFromBranch) {
+		return featureFromBranch;
+	}
+
+	const features = listFeatureDirs(repoRoot);
+	if (features.length === 0) {
+		return undefined;
+	}
+	if (features.length === 1) {
+		return features[0];
+	}
+	if (!ctx.hasUI || typeof ctx.ui.select !== "function") {
+		return getLatestFeatureDir(repoRoot);
+	}
+	const selected = await ctx.ui.select("Select active spec feature", features);
+	return selected || undefined;
+}
+
+async function resolveFeaturePaths(
+	ctx: ExtensionCommandContext,
+	repoRoot: string,
+	currentBranch: string,
+): Promise<WorkflowPaths | undefined> {
+	const featureName = await resolveActiveFeatureName(ctx, repoRoot, currentBranch);
+	if (!featureName) {
+		ctx.ui.notify("No active feature found. Run /spec specify <feature description> first.", "warning");
+		return undefined;
+	}
+	return buildWorkflowPaths(repoRoot, featureName);
+}
+
+function queueWorkflow(
+	pi: ExtensionAPI,
+	step: WorkflowStep,
+	currentBranch: string,
+	paths: WorkflowPaths,
+	input: string,
+): void {
+	const prompt = buildWorkflowPrompt({
+		step,
+		input,
+		paths,
+		currentBranch,
+		workflowTemplatePath: getWorkflowTemplatePath(paths, step),
+		stepNotes: getStepNotes(step),
+		checklists: step === "implement" ? summarizeChecklists(paths.checklistsDir) : undefined,
+	});
+	pi.sendUserMessage(prompt);
+}
+
+async function collectStepInput(ctx: ExtensionCommandContext, step: WorkflowStep, existing: string): Promise<string> {
+	if (existing.trim() || !stepNeedsRequiredInput(step)) {
+		return existing.trim();
+	}
+
+	const titleByStep: Record<WorkflowStep, string> = {
+		constitution: "Describe the constitution principles",
+		specify: "Describe the feature to specify",
+		clarify: "Optional clarification focus",
+		checklist: "Optional checklist focus or domain",
+		plan: "Describe the technical context",
+		tasks: "Optional task-generation context",
+		analyze: "Optional analysis focus",
+		implement: "Optional implementation focus",
+	};
+
+	return (
+		(await promptForMissingInput(ctx, titleByStep[step], "Write the details for this /spec step here")) ?? ""
+	).trim();
+}
+
+function makeEnv(ctx: ExtensionCommandContext, git = createGitClient()) {
+	const { repoRoot, hasGit } = findRepoRoot(ctx.cwd, git);
+	const currentBranch = git.getCurrentBranch(repoRoot) ?? process.env.SPECIFY_FEATURE ?? "main";
+	const basePaths = buildWorkflowPaths(repoRoot);
+	return { git, repoRoot, hasGit, currentBranch, basePaths };
+}
+
+function handleInit(pi: ExtensionAPI, repoRoot: string, created: string[]): void {
+	sendReport(
+		pi,
+		[
+			"# /spec init",
+			"",
+			`- Repository root: ${repoRoot}`,
+			formatCreatedFiles(created),
+			"",
+			"Next: `/spec constitution <principles>` or `/spec specify <feature description>`.",
+		].join("\n"),
+	);
+}
+
+async function handleStatus(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	repoRoot: string,
+	currentBranch: string,
+): Promise<void> {
+	const activeFeature = await resolveActiveFeatureName(ctx, repoRoot, currentBranch);
+	sendReport(
+		pi,
+		formatWorkflowStatus(
+			buildWorkflowStatus({
+				repoRoot,
+				currentBranch,
+				paths: buildWorkflowPaths(repoRoot, activeFeature),
+				activeFeature,
+			}),
+		),
+	);
+}
+
+async function handleNext(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	repoRoot: string,
+	currentBranch: string,
+): Promise<void> {
+	const activeFeature = await resolveActiveFeatureName(ctx, repoRoot, currentBranch);
+	const status = buildWorkflowStatus({
+		repoRoot,
+		currentBranch,
+		paths: buildWorkflowPaths(repoRoot, activeFeature),
+		activeFeature,
+	});
+	sendReport(pi, `# Next /spec steps\n\n${status.nextSteps.map((step) => `- ${step}`).join("\n")}`);
+}
+
+function handleSpecify(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	env: ReturnType<typeof makeEnv>,
+	input: string,
+): void {
+	if (!input) {
+		ctx.ui.notify("/spec specify requires a feature description.", "warning");
+		return;
+	}
+
+	try {
+		const prepared = prepareFeatureWorkspace({
+			repoRoot: env.repoRoot,
+			description: input,
+			git: env.git,
+			currentBranch: env.currentBranch,
+			hasGit: env.hasGit,
+		});
+		const paths = buildWorkflowPaths(env.repoRoot, prepared.branchName);
+		ensureWorkflowScaffold(paths);
+		ensureFeatureArtifacts(paths);
+		queueWorkflow(pi, "specify", prepared.branchName, paths, input);
+		sendReport(
+			pi,
+			[
+				"# /spec specify",
+				"",
+				`- Feature branch: ${prepared.branchName}`,
+				`- Feature number: ${prepared.featureNumber}`,
+				`- Feature directory: ${prepared.featureDir}`,
+				`- Spec file: ${prepared.specFile}`,
+				"",
+				"Queued the native specification workflow as a user message.",
+			].join("\n"),
+		);
+	} catch (error) {
+		ctx.ui.notify(
+			`Failed to prepare feature workspace: ${error instanceof Error ? error.message : String(error)}`,
+			"error",
+		);
+	}
+}
+
+async function confirmChecklistOverride(ctx: ExtensionCommandContext, paths: WorkflowPaths): Promise<boolean> {
+	const checklists = summarizeChecklists(paths.checklistsDir);
+	if (
+		!(checklists.some((checklist) => checklist.incomplete > 0) && ctx.hasUI && typeof ctx.ui.confirm === "function")
+	) {
+		return true;
+	}
+
+	const proceed = await ctx.ui.confirm(
+		"Incomplete spec checklists",
+		`${checklists.map((checklist) => `${checklist.name}: ${checklist.incomplete} incomplete item(s)`).join("\n")}
+
+Proceed with implementation anyway?`,
+	);
+	if (!proceed) {
+		ctx.ui.notify("Implementation cancelled until the checklist review is complete.", "info");
+	}
+	return proceed;
+}
+
+async function handleWorkflowStep(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	env: ReturnType<typeof makeEnv>,
+	step: WorkflowStep,
+	input: string,
+): Promise<void> {
+	if (step === "specify") {
+		handleSpecify(pi, ctx, env, input);
+		return;
+	}
+
+	const featurePaths =
+		step === "constitution"
+			? buildWorkflowPaths(env.repoRoot, await resolveActiveFeatureName(ctx, env.repoRoot, env.currentBranch))
+			: await resolveFeaturePaths(ctx, env.repoRoot, env.currentBranch);
+	ensureWorkflowScaffold(featurePaths ?? env.basePaths);
+	if (!featurePaths) {
+		return;
+	}
+
+	if (step === "plan") {
+		ensurePlanArtifact(featurePaths);
+	}
+	if (step === "implement" && !(await confirmChecklistOverride(ctx, featurePaths))) {
+		return;
+	}
+
+	queueWorkflow(pi, step, env.currentBranch, featurePaths, input);
+	ctx.ui.notify(`Queued /spec ${step} workflow.`, "info");
+}
+
+export default function specExtension(pi: ExtensionAPI) {
+	pi.registerMessageRenderer(REPORT_MESSAGE_TYPE, (message, _options, theme) => {
+		const text = `${theme.fg("accent", theme.bold("spec"))}\n\n${String(message.content ?? "")}`;
+		return new Text(text, 0, 0);
+	});
+
+	pi.registerCommand("spec", {
+		description:
+			"Native spec-kit workflow for pi (/spec init|constitution|specify|clarify|checklist|plan|tasks|analyze|implement)",
+		getArgumentCompletions(prefix) {
+			const trimmed = prefix.trimStart();
+			if (trimmed.includes(" ")) {
+				return null;
+			}
+			const values = SPEC_SUBCOMMANDS.filter((command) => command.startsWith(trimmed)).map((command) => ({
+				value: command,
+				label: command,
+			}));
+			return values.length > 0 ? values : null;
+		},
+		handler: async (rawArgs, ctx) => {
+			const { subcommand, remainder } = tokenize(rawArgs);
+			if (!subcommand) {
+				ctx.ui.notify(`Unknown /spec subcommand: ${rawArgs.trim()}`, "warning");
+				sendReport(pi, formatHelpReport());
+				return;
+			}
+
+			const env = makeEnv(ctx);
+			if (subcommand === "init") {
+				handleInit(pi, env.repoRoot, ensureWorkflowScaffold(env.basePaths));
+				return;
+			}
+			if (subcommand === "help") {
+				sendReport(pi, formatHelpReport());
+				return;
+			}
+			if (subcommand === "list") {
+				sendReport(pi, formatFeatureList(env.repoRoot));
+				return;
+			}
+			if (subcommand === "status") {
+				await handleStatus(pi, ctx, env.repoRoot, env.currentBranch);
+				return;
+			}
+			if (subcommand === "next") {
+				await handleNext(pi, ctx, env.repoRoot, env.currentBranch);
+				return;
+			}
+			if (!isWorkflowStep(subcommand)) {
+				sendReport(pi, formatHelpReport());
+				return;
+			}
+
+			const input = await collectStepInput(ctx, subcommand, remainder);
+			await handleWorkflowStep(pi, ctx, env, subcommand, input);
+		},
+	});
+}