@abianbiya/specflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abian Nur Amin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @abianbiya/specflow
+
+Spec-driven development for [pi](https://pi.dev) — full SpecFlow workflow (Requirements → Design → Tasks → Execution with explicit review gates) plus a live cockpit panel that shows where every spec stands and when the agent is waiting on your approval.
+
+Installing this package gives you two things:
+
+1. **The `specflow` skill** — the structured five-phase workflow: drafting `.specflow/specs/{feature}/` documents (requirements, design, tasks), explicit approval gates between phases, validated task execution, and lifecycle management (complete, archive, list, resume).
+2. **The SpecFlow TUI extension** — a live cockpit panel for the active spec (phase, progress, next actionable task, traceability warnings, and a gate badge when the agent is parked awaiting your review), plus a `/specflow` command that can **launch work** — execute a task, approve a gate and resume, validate — as well as switch specs and read documents. The extension itself never writes to `.specflow/`: every action reaches the agent as an explicit user message, so the skill stays the only writer.
+
+## Install
+
+```bash
+pi install npm:@abianbiya/specflow
+```
+
+Or try it without installing:
+
+```bash
+pi -e npm:@abianbiya/specflow
+```
+
+For development against a local checkout:
+
+```bash
+pi install -l /absolute/path/to/specflow-pi
+```
+
+## Usage
+
+- Ask for a feature and the agent drafts requirements, then design, then tasks — each stopping for your approval (the panel shows `awaiting your review` at every stop).
+- Live panel — the selected spec's name, phase (Requirements / Design / Tasks / Executing), done/total task count, status, and gate badge, updating within ~0.5 s of file edits.
+- `/specflow` — act on the active spec without leaving the terminal:
+  - **Execute a task…** — pick from the unfinished tasks (`▶` ready, `⏸` blocked, with what they wait on); the chosen task is sent to the agent as `Execute task 2.1 of the rate-limit spec.`
+  - **Approve gate and resume** — appears only while a review gate is pending
+  - **Validate implementation** / **Open document…** — `requirements.md`, `design.md`, `tasks.md`, or `project.md` in a scrollable popup
+  - **Hide/Show panel**, and the spec list to switch which spec the panel follows
+- Panel rows, beyond the phase: `Next: 2.1 Wire the Fastify hook` (first task whose dependencies are done), and one warning row when traceability is incomplete — `⚠ 1 unclaimed AC · 1 orphan criterion · 1 dangling dep`, i.e. requirements no task implements, citations of ACs that don't exist, and `Depends on:` ids that don't resolve.
+- `resume` / `complete` / `archive` — lifecycle routes from the skill; the panel reflects the reconciled state.
+
+## Companion package
+
+[`@abianbiya/speclet`](https://www.npmjs.com/package/@abianbiya/speclet) is the lightweight sibling: single-file specs for small features. Use specflow for mid-to-large features with multiple review gates.
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,323 @@
+/**
+ * specflow-pi — Pi extension. Shows the active specflow's phase as a live
+ * widget above the editor and registers the /specflow picker command, which
+ * also opens requirements.md / design.md / tasks.md / project.md in a
+ * scrollable markdown popup.
+ *
+ * State is always read from `<cwd>/.specflow/`; this extension never writes
+ * there (the skill owns gate metadata). A 500 ms non-overlapping poll keeps
+ * the panel current.
+ *
+ * Declared fork of speclet-tui/index.ts (AC7). Deliberately absent: the
+ * speclet task inspector and its `shift+up` registration — dropping the only
+ * global shortcut is what lets both extensions coexist in one session.
+ */
+
+import { join } from "node:path";
+import { lstat, readFile } from "node:fs/promises";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { matchesKey, Markdown, truncateToWidth, type MarkdownTheme } from "@earendil-works/pi-tui";
+import { SpecflowController } from "../src/controller.js";
+import { discoverSpecflows, type SpecflowSpec } from "../src/parse.js";
+import { renderScrollbar, stripControlSequences } from "../src/shared.js";
+import {
+	actionOptions,
+	documentOptions,
+	listText,
+	pickerOptions,
+	renderWidgetLines,
+	renderDetailsLines,
+	taskOptions,
+	type CockpitAction,
+	type Styler,
+} from "../src/render.js";
+
+const WIDGET_KEY = "specflow";
+const MAX_LINES = 6;
+const INDENT = "  ";
+/** Viewer ceiling: larger or binary documents are reported, never rendered (F5). */
+const MAX_DOC_BYTES = 512 * 1024;
+
+function popupColors() {
+	return {
+		heading: "accent",
+		meta: "muted",
+		phase: "text",
+		gate: "warning",
+		next: "text",
+		warn: "warning",
+		body: "text",
+		more: "dim",
+		rule: "borderMuted",
+	} as const;
+}
+
+function makeStyler(theme: any): Styler {
+	const colors = popupColors();
+	return (text, kind) => theme.fg(colors[kind], text);
+}
+
+function markdownThemeFrom(theme: any): MarkdownTheme {
+	return {
+		heading: (t) => theme.fg("accent", theme.bold(t)),
+		link: (t) => theme.fg("accent", t),
+		linkUrl: (t) => theme.fg("dim", t),
+		code: (t) => theme.fg("warning", t),
+		codeBlock: (t) => theme.fg("dim", t),
+		codeBlockBorder: (t) => theme.fg("borderMuted", t),
+		quote: (t) => theme.fg("dim", t),
+		quoteBorder: (t) => theme.fg("borderMuted", t),
+		hr: (t) => theme.fg("borderMuted", t),
+		listBullet: (t) => theme.fg("accent", t),
+		bold: (t) => theme.bold(t),
+		italic: (t) => theme.italic(t),
+		strikethrough: (t) => theme.strikethrough(t),
+		underline: (t) => theme.underline(t),
+	};
+}
+
+interface PopupCtx {
+	ui: {
+		custom: (factory: unknown, options?: unknown) => Promise<void>;
+		notify: (message: string, type?: string) => void;
+	};
+}
+
+/**
+ * Open one document overlay: themed markdown, padded box, scrollbar, esc/q
+ * closes (AC4). A missing or unreadable file reports the file name and opens
+ * nothing.
+ */
+async function openDocumentPopup(
+	popupCtx: PopupCtx,
+	spec: SpecflowSpec,
+	doc: { label: string; path: string },
+): Promise<void> {
+	let content: string;
+	try {
+		const stats = await lstat(doc.path);
+		if (stats.size > MAX_DOC_BYTES) {
+			popupCtx.ui.notify(
+				`specflow: cannot display ${doc.label}: ${Math.round(stats.size / 1024)} kB exceeds the ${MAX_DOC_BYTES / 1024} kB viewer limit`,
+				"error",
+			);
+			return;
+		}
+		content = await readFile(doc.path, "utf8");
+	} catch (e) {
+		popupCtx.ui.notify(`specflow: cannot read ${doc.label}: ${String(e)}`, "error");
+		return;
+	}
+	if (content.includes("\u0000")) {
+		popupCtx.ui.notify(`specflow: cannot display ${doc.label}: binary file`, "error");
+		return;
+	}
+	const header = `${spec.name} · ${doc.label}`;
+
+	await popupCtx.ui.custom(
+		(tui: any, theme: any, _keybindings: unknown, close: () => void) => {
+			let offset = 0;
+			const styler = makeStyler(theme);
+			const mdTheme = markdownThemeFrom(theme);
+			let md: Markdown | undefined;
+			let mdBodyLines: string[] = [];
+			let mdWidth = -1;
+			const height = () => Math.max(8, Math.floor(tui.terminal.rows * 0.7));
+			return {
+				render(width: number): string[] {
+					// true inner width: border(4) + indent(2) + scrollbar column(2)
+					const contentWidth = Math.max(10, width - 8);
+					if (!md || mdWidth !== contentWidth) {
+						md = new Markdown(content, 0, 0, mdTheme);
+						mdWidth = contentWidth;
+						mdBodyLines = md.render(contentWidth);
+						offset = Math.max(0, Math.min(offset, Math.max(0, mdBodyLines.length - 1)));
+					}
+					const h = height();
+					const visibleRows = Math.max(1, h - 3);
+					const bar = renderScrollbar(mdBodyLines.length, visibleRows, offset).map((c) =>
+						c === "█" ? theme.fg("accent", "█") : theme.fg("borderMuted", "░"),
+					);
+					return renderDetailsLines(header, mdBodyLines, width, h, offset, truncateToWidth, styler, {
+						indent: INDENT,
+						scrollbar: bar,
+						plainBody: true,
+						border: true,
+					});
+				},
+				handleInput(data: string): void {
+					if (matchesKey(data, "escape") || data === "q") {
+						close();
+						return;
+					}
+					const page = Math.max(1, height() - 4);
+					const delta = matchesKey(data, "down")
+						? 1
+						: matchesKey(data, "up")
+							? -1
+							: matchesKey(data, "pageDown")
+								? page
+								: matchesKey(data, "pageUp")
+									? -page
+									: matchesKey(data, "home")
+										? -Infinity
+										: matchesKey(data, "end")
+											? Infinity
+											: 0;
+					if (delta === 0) return;
+					const visibleRows = Math.max(1, height() - 3);
+					offset = Math.max(0, Math.min(offset + delta, Math.max(0, mdBodyLines.length - visibleRows)));
+					tui.requestRender();
+				},
+				invalidate(): void {
+					md = undefined;
+				},
+			};
+		},
+		{ overlay: true, overlayOptions: { width: "80%", margin: 2 } },
+	);
+}
+
+/**
+ * Run one cockpit action (AC6). Every action reaches the agent as an explicit
+ * user message via pi.sendUserMessage — this extension never writes to
+ * `.specflow/` itself, so the skill/agent stays the only writer. Cancelling a
+ * chooser performs nothing (AC7).
+ */
+async function runCockpitAction(
+	pi: ExtensionAPI,
+	ctx: { ui: { select: (title: string, options: string[]) => Promise<string | undefined>; notify: (m: string, t?: string) => void } },
+	spec: SpecflowSpec,
+	action: CockpitAction,
+	projectFile: string,
+): Promise<void> {
+	const confirm = (message: string) => {
+		pi.sendUserMessage(message);
+		ctx.ui.notify(`Sent: ${message}`, "info");
+	};
+
+	switch (action) {
+		case "execute": {
+			const tasks = taskOptions(spec);
+			if (tasks.length === 0) {
+				ctx.ui.notify(`No unfinished task in ${spec.name}.`, "info");
+				return;
+			}
+			const choice = await ctx.ui.select(`Execute which task of ${spec.name}?`, tasks.map((t) => t.label));
+			if (choice === undefined) return;
+			const picked = tasks.find((t) => t.label === choice);
+			if (!picked) return;
+			confirm(`Execute task ${picked.task.id} of the ${spec.name} spec.`);
+			return;
+		}
+		case "approve":
+			confirm(`Approve and resume the ${spec.name} spec.`);
+			return;
+		case "validate":
+			confirm(`Validate the ${spec.name} spec implementation.`);
+			return;
+		case "document": {
+			const docs = documentOptions(spec, projectFile);
+			const picked = await ctx.ui.select(`Document: ${spec.name}`, docs.map((d) => d.label));
+			if (picked === undefined) return;
+			const doc = docs.find((d) => d.label === picked);
+			if (doc) await openDocumentPopup(ctx, spec, doc);
+			return;
+		}
+		case "toggle":
+			return; // handled by the caller, which owns the controller
+	}
+}
+
+export default function specflowTui(pi: ExtensionAPI) {
+	let controller: SpecflowController | undefined;
+
+	// Re-register the widget from current controller state. setWidget with a
+	// factory triggers a repaint; the component re-reads state on each render so
+	// resize always reflows. No specflow widget when the panel has no content.
+	function repaint(ctx: { ui: { setWidget: (key: string, content: unknown) => void } }) {
+		if (!controller) return;
+		const spec = controller.active();
+		if (!spec || controller.hidden) {
+			ctx.ui.setWidget(WIDGET_KEY, undefined);
+			return;
+		}
+
+		ctx.ui.setWidget(WIDGET_KEY, (_tui, theme) => ({
+			render(width: number): string[] {
+				const current = controller?.active();
+				if (!current) return [];
+				return renderWidgetLines(current, width, MAX_LINES, truncateToWidth, makeStyler(theme));
+			},
+		}));
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		// Interactive-only: no timer or widget in rpc/json/print modes (AC6).
+		if (ctx.mode !== "tui") return;
+		const sessionCtx = ctx;
+		controller = new SpecflowController(join(ctx.cwd, ".specflow"), {
+			onUpdate: () => repaint(sessionCtx),
+			onDiagnostic: (msg) => sessionCtx.ui.notify(`specflow: ${msg}`, "warning"),
+		});
+		repaint(sessionCtx);
+		controller.start();
+	});
+
+	pi.on("session_shutdown", () => {
+		// Stop polling and drop session state (incl. pinned selection) — AC6.
+		controller?.stop();
+		controller = undefined;
+	});
+
+	pi.registerCommand("specflow", {
+		description: "Act on the active specflow: execute a task, approve a gate, validate, or read a document",
+		handler: async (_args, ctx) => {
+			const specflowDir = join(ctx.cwd, ".specflow");
+
+			// Non-interactive modes: textual listing, never a dialog (AC3, AC8).
+			// A partial discovery failure must not hide the specs that did resolve (F4).
+			if (ctx.mode !== "tui" || !controller) {
+				const { specs, dirError } = await discoverSpecflows(specflowDir);
+				const listing = specs.length > 0 ? listText(specs) : "No specflows found.";
+				const text = stripControlSequences(dirError ? `${dirError}\n${listing}` : listing);
+				if (ctx.hasUI) {
+					ctx.ui.notify(text, "info");
+				} else {
+					console.log(text);
+				}
+				return;
+			}
+
+			if (controller.specs.length === 0) {
+				ctx.ui.notify("No specflows found.", "info");
+				return;
+			}
+
+			const active = controller.active();
+			const options = pickerOptions(controller.specs);
+			const actions = active ? actionOptions(active, controller.hidden) : [];
+			const choice = await ctx.ui.select(active ? `Specflow: ${active.name}` : "Specflow:", [
+				...actions.map((a) => a.label),
+				...options.map((o) => o.label),
+			]);
+			if (choice === undefined) return; // cancelled — keep current selection (AC3, AC7)
+
+			const action = actions.find((a) => a.label === choice);
+			if (action && active) {
+				if (action.action === "toggle") {
+					controller.hidden ? controller.show() : controller.hide();
+					return;
+				}
+				await runCockpitAction(pi, ctx, active, action.action, join(specflowDir, "project.md"));
+				return;
+			}
+
+			const picked = options.find((o) => o.label === choice);
+			if (picked) {
+				controller.pin(picked.dir);
+				controller.show(); // picking a specflow also reveals the panel
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@abianbiya/specflow",
+	"version": "0.1.0",
+	"description": "SpecFlow for pi: spec-driven development with review gates (skill), plus a live spec cockpit panel, /specflow picker, and in-terminal document viewer (TUI extension).",
+	"type": "module",
+	"license": "MIT",
+	"keywords": [
+		"pi-package",
+		"spec-driven",
+		"specflow",
+		"skills",
+		"agent"
+	],
+	"files": [
+		"skills",
+		"extensions",
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"test": "bun test",
+		"prepublishOnly": "bun run scripts/sync-skill.ts --check && bun run scripts/check-fork.ts"
+	},
+	"pi": {
+		"extensions": ["./extensions"],
+		"skills": ["./skills"]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"peerDependenciesMeta": {
+		"@earendil-works/pi-coding-agent": { "optional": true },
+		"@earendil-works/pi-tui": { "optional": true }
+	}
+}

package/skills/specflow/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: specflow
+description: "Plan and implement features through approved requirements, design, and tasks. Use for spec-driven development with explicit review gates and validated execution."
+---
+
+# SpecFlow
+
+## Core Contract
+
+Work through Phase 1 (Requirements), Phase 2 (Design), Phase 3 (Tasks), then Phase 4 (Execution). Present each planning document for review and obtain explicit approval before advancing; revise and seek approval again after feedback. Existing files alone are not approval. When updating an earlier phase, reconcile affected downstream documents through the same gates before execution.
+
+Phase 4 defaults to one task, followed by a report and a stop for user review. Only an explicitly requested task range or list authorizes a batch. Phase 5 manages completion, archiving, listing, and resumption; it is not an additional planning gate.
+
+Whenever work pauses for a review — a planning document or a Phase 4 task report — record `gate: review` in the spec's `tasks.md` frontmatter (create a metadata-only `tasks.md` when none exists) and clear the field once approval to resume is received.
+
+Load the relevant reference when entering a phase; reuse context already loaded and unchanged. Start the requested work without an unsolicited workflow explanation.
+
+## Entry Points
+
+| User intent | Route / reference |
+|-------------|-------------------|
+| First spec / missing project.md | [Project setup](references/project-setup.md), then requested phase |
+| New feature / new spec / update requirements | [Phase 1: Requirements](references/requirements-phase.md) |
+| Grill me / ask me questions first / let's discuss this | [Phase 1: Grilling](references/requirements-phase.md#grilling-optional) |
+| Update design / grill the design / discuss architecture first | [Phase 2: Design](references/design-phase.md) |
+| Update tasks | [Phase 3: Tasks](references/tasks-phase.md) |
+| Execute a task / execute next task | [Phase 4: Execution](references/execution-phase.md) |
+| Execute tasks 1.1–1.4 / an explicit task list | [Phase 4: Execution](references/execution-phase.md) within that scope |
+| Execute an authorized batch in parallel | [Phase 4: Parallel execution](references/execution-phase.md#parallel-execution-optional) |
+| Validate implementation | [Phase 4: Validation](references/execution-phase.md#validation) |
+| Continue / resume spec | [Phase 5: Resume](references/lifecycle-phase.md#resume) to determine the current phase |
+| Complete spec / mark spec done | [Phase 5: Complete](references/lifecycle-phase.md#complete) |
+| Archive spec | [Phase 5: Archive](references/lifecycle-phase.md#archive) |
+| List / show specs, optionally by status | [Phase 5: List](references/lifecycle-phase.md#list) |
+
+## Directory Layout
+
+```text
+.specflow/
+├── project.md
+└── specs/
+    └── {feature-name}/
+        ├── requirements.md
+        ├── design.md
+        └── tasks.md
+```
+
+Use descriptive kebab-case feature names. Status lives in `tasks.md` frontmatter; paths stay stable. Older versions used `active/`, `completed/`, and `archived/` directories: preserve compatibility as described in [Lifecycle](references/lifecycle-phase.md#status-and-legacy-layout).

package/skills/specflow/references/design-phase.md

@@ -0,0 +1,27 @@
+# Phase 2: Design
+
+Use the approved requirements and current project context to create or update `design.md` in the active feature directory. Follow the [planning approval gate](../SKILL.md#core-contract).
+
+Research the codebase and external dependencies as needed. Summarize findings with sources and links in the conversation; do not create separate research files. Record unresolved research limitations and their impact. Consult relevant completed specs through the dependency links in requirements.
+
+## Grilling (Optional)
+
+When requested, use the [grilling format](requirements-phase.md#grilling-optional) for architectural decisions that materially affect the design: data ownership and models, coupling, consistency, API contracts, and access boundaries. Capture confirmed choices and rationale in Design Decisions.
+
+## Document Content
+
+| Section | Required content |
+|---------|------------------|
+| Overview | Technical approach and how it meets requirements |
+| Architecture | System context, component boundaries and interactions, Mermaid diagram |
+| Design Decisions | Options considered, choice, rationale |
+| Components and Interfaces | Responsibilities, dependencies, method signatures, parameters and return types |
+| Data Models | Fields, types, constraints, relationships; diagram where useful |
+| API Design (if applicable) | Methods, paths, requests, responses, error contracts |
+| Error Handling | Error categories, user impact, recovery/retry/fallback behavior |
+| Testing Strategy | Unit, integration, and E2E scenarios as applicable; component coverage and project testing standards |
+| Security Considerations | Access controls, relevant threats, data privacy |
+| Performance Considerations | Expected load, capacity, caching and query behavior as applicable |
+| Requirements Traceability | Map every requirement to design components using the [requirement IDs](requirements-phase.md#document-content) |
+
+Keep the design sufficient to implement and verify all requirements without prescribing unrelated layers or technologies. Present it with a summary of key decisions for review.

package/skills/specflow/references/execution-phase.md

@@ -0,0 +1,55 @@
+# Phase 4: Execution
+
+## Session Context
+
+Identify the active spec and verify the [planning approvals](../SKILL.md#core-contract). Project context must exist; all three planning documents must be approved.
+
+At the start of an execution session, read `.specflow/project.md` and the feature's `requirements.md`, `design.md`, and `tasks.md` in full once. Load referenced completed-spec context only where relevant. Retain the requirement mapping, design structure, task order/dependencies, and project conventions in session context.
+
+An execution session spans successive task requests for the same spec while that context remains available. A user-review pause does not start a new session. If context is lost or a different spec is selected, establish the full baseline again. If files change, refresh affected sections and dependencies; changes to approved planning content must pass the root approval gates before execution resumes.
+
+## Task Scope and Delta Reads
+
+For “execute next task,” select the first unchecked task in listed order whose declared dependencies are validated and integrated. For a specified task, verify that it is unchecked and its dependencies are complete. An explicit range such as “execute tasks 1.1–1.4” or list authorizes those tasks only, in dependency order, sequentially by default; do not silently add prerequisites or expand the range. Skip already checked tasks and report them as skipped.
+
+For each task after the baseline, load only:
+
+- Its current unchecked task line and scope/reference sub-bullets, plus dependency or parent status needed to select it.
+- The referenced requirement IDs and their acceptance criteria, using the [ID convention](requirements-phase.md#document-content).
+- The design sections it touches, including relevant shared interfaces and constraints.
+
+Reuse unchanged project and broader spec context; do not reload entire documents per task. Resolve unclear scope from these excerpts before asking the user. Missing IDs, unmet dependencies, or remaining ambiguity block execution of that task.
+
+Implement within this scope using the approved design and project conventions. Requirements and design are read-only during execution; route needed changes to their planning phase. Clarified task wording may be updated without silently changing approved scope.
+
+## Parallel Execution (Optional)
+
+Use subagents only within an explicitly authorized batch, when the user permits delegation and the harness supports it. Otherwise follow the same dependency flow sequentially. Only ready tasks with no dependency between them may run together.
+
+The parent assigns bounded task scopes, relevant context excerpts, and file ownership. Use disjoint files where shared-tree parallel writers are permitted; otherwise use separate worktrees or run sequentially. Account for shared interfaces, generated files, and mutable test resources as well as dependency edges. Follow harness limits and repository delegation rules.
+
+Children implement and return changes plus validation evidence; the parent owns integration, final validation, and `tasks.md` updates. A child report alone does not complete a task. Integrate and validate prerequisite results before launching dependents.
+
+On an unresolved failure, stop dispatching new tasks, safely pause or collect already-running work, preserve edits, and report completed, failed, and unstarted tasks. Do not start dependents of failed work.
+
+## Validation
+
+Before changing a task checkbox, verify all three levels:
+
+| Level | Evidence required |
+|-------|-------------------|
+| Requirements | Every referenced acceptance criterion passes, including its specified edge, error, and success cases. A whole-requirement reference includes all its criteria. |
+| Design | Touched components/layers, schemas and relationships, interfaces, API behavior, error handling, and state management match the approved design. |
+| Quality | Tests for new testable logic cover normal and error paths; project tests, lint, and applicable type checks pass; functionality runs without errors or warnings. Find commands in project context or repository configuration. |
+
+If a task cannot independently satisfy its referenced criteria, resolve the task/spec mismatch through planning rather than claiming partial validation as a pass. If checks fail, fix within the authorized task and revalidate. If blocked or unable to run required checks, leave it unchecked, report the evidence and resolution options, and stop for user guidance. For a parallel batch, apply the failure handling above.
+
+Only after all levels pass, change that task from `- [ ]` to `- [x]`. Complete children before checking a parent; check the parent's own scope too. In sequential execution, validate and update each task before starting the next; parallel execution follows the integration rules above.
+
+For “validate implementation,” apply these same levels to the requested scope (the whole implementation if unspecified), using the session/delta context rules. Report findings without implementing fixes or changing checkboxes unless requested.
+
+## Report and Stop
+
+Report task IDs and outcomes, changed files, requirement/criterion evidence, design conformance, checks run and results, and any blockers or remaining work. For a batch, give one consolidated report with per-task results, including skipped or unexecuted tasks.
+
+Stop after the default single task or the explicitly authorized batch and wait for the user before further execution. When all tasks are checked, report readiness for the explicit [complete spec](lifecycle-phase.md#complete) action; do not change its lifecycle status automatically.

package/skills/specflow/references/lifecycle-phase.md

@@ -0,0 +1,57 @@
+# Phase 5: Lifecycle
+
+## Status and Legacy Layout
+
+New specs use the flat [layout](../SKILL.md#directory-layout). `tasks.md` frontmatter status is authoritative: `active` for development, `completed` for implementation references, `archived` for obsolete or abandoned history. Before a new plan exists, treat the spec as active. Listing, resuming, and archiving are available before implementation finishes.
+
+Older versions stored specs under `specs/active/`, `specs/completed/`, and `specs/archived/`. Discover both layouts; for legacy specs without status metadata, infer status from the containing directory. Metadata takes precedence if present. Update legacy specs in place without moving directories or migrating automatically. A flat spec with a task file but missing or invalid status needs clarification before a lifecycle write.
+
+Resolve names across both layouts, using actual paths to distinguish duplicates. Use the sole eligible spec if unambiguous; otherwise ask which spec. Report missing specs or already-achieved states without changing anything.
+
+## Complete
+
+On an explicit completion request, verify the active spec's tasks are all checked and their completion is backed by [execution validation](execution-phase.md#validation). Unchecked or unvalidated work blocks completion; report what remains. This command does not implement tasks or check boxes on the user's behalf.
+
+Set completion metadata in place. Confirm the spec path, status, and completion date. Completed specs remain available as reference documentation.
+
+## Archive
+
+On an archive request, set archive metadata on an active or completed spec in place. Use the user's reason if supplied; otherwise ask and wait for it. Confirm the spec path, status, reason, and archive date.
+
+Archive rather than delete specs. Preserve all documents and historical metadata; lifecycle transitions do not move directories. Verify metadata after writing and report failures. Archived specs can be referenced but not modified.
+
+## Metadata
+
+Store lifecycle metadata in YAML frontmatter at the top of `tasks.md`, preserving unrelated fields and body. For an early archive with no task file, create a metadata-only `tasks.md`; this is not an approved implementation plan.
+
+| Field | Rule |
+|-------|------|
+| status | Set `active` when creating a plan; preserve existing status on plan edits; set `completed` or `archived` only through the corresponding transition |
+| gate | Only defined value is `review`: set when stopping for a review in any phase (planning documents and every Phase 4 per-task stop); clear when approval to resume is received |
+| created_at | Preserve if present; record only if the creation date is known |
+| completed_at | Set to today's ISO date (YYYY-MM-DD) on completion; preserve on later archive |
+| archived_at | Set to today's ISO date on archive |
+| archive_reason | User-supplied reason, required on archive |
+
+Use status resolution above for legacy plans. A metadata-only task file is not evidence of planning approval.
+
+## List
+
+Show specs grouped by active/completed/archived, or restrict to the requested status. Task counts, lifecycle dates, and archive reasons may supplement names. Distinguish executable-task progress from parent group checkboxes when reporting counts.
+
+## Resume
+
+Locate the active spec and determine progress from documents plus known approvals, not file existence alone. If approval is unknown, request review of the relevant document before advancing.
+
+| State | Route |
+|-------|-------|
+| No requirements | Phase 1: [Requirements](requirements-phase.md) |
+| Requirements awaiting approval | Phase 1 review |
+| Requirements approved; design missing or awaiting approval | Phase 2: [Design](design-phase.md) / review |
+| Design approved; tasks missing or awaiting approval | Phase 3: [Tasks](tasks-phase.md) / review |
+| All three approved, work remains | Phase 4: [Execution](execution-phase.md), default next task |
+| All tasks validated and checked | Report readiness for Complete; await explicit completion request |
+
+Reconcile recorded gate state on resume: a `gate: review` field that no longer matches a pending review — for example one left behind by an interrupted session — must be cleared.
+
+Report the current phase, progress if available, and next action. Let the selected phase load its relevant context; resumption does not itself mandate full-document re-reading.

package/skills/specflow/references/project-setup.md

@@ -0,0 +1,9 @@
+# Project Setup
+
+`.specflow/project.md` holds shared tech stack, conventions, and patterns. Use it when creating or updating specs; retain unchanged context during the session. Execution loading and refresh rules are defined in [Phase 4](execution-phase.md#session-context).
+
+If missing, create it before the first spec using [templates/project.md](../templates/project.md). Inspect available project information and ask the user for missing stack or convention details needed to fill it out.
+
+The template is the canonical starting point. Add project-specific package-manager and lint/format tooling, actual test/lint/type-check/dev-server commands where applicable, directory layout, and integration notes when available; these operational details supplement its existing sections.
+
+Update project context when the stack, conventions, or major directory structure changes. Current project context takes precedence over conflicting completed-spec conventions; resolve conflicts with active approved specs through their planning gates.