@abianbiya/specflow 0.1.0

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

@@ -0,0 +1,33 @@
+# Phase 1: Requirements
+
+Use project context from `.specflow/project.md`; if missing, follow [project setup](project-setup.md). Create or update `requirements.md` in the active feature directory defined in [SKILL.md](../SKILL.md#directory-layout). Consult related completed specs when relevant, resolving status through [Lifecycle](lifecycle-phase.md#status-and-legacy-layout). Link to their actual paths (`../{feature-name}/` in the flat layout).
+
+Generate an initial draft from the idea without a preliminary interview unless grilling is requested. Identify assumptions and unresolved information rather than silently inventing scope.
+
+## Grilling (Optional)
+
+When requested, surface contextual questions whose answers would materially change the spec: ambiguities, concurrency, edge cases, hidden decisions, or integration constraints. Present one block, each question paired with a recommendation and brief reasoning. Wait for answers before drafting; use the confirmed intent.
+
+## Document Content
+
+- Introduction: what, why, intended users, and scope.
+- Numbered requirements, each with a descriptive name, a user story (As a role, I want a capability, so that a benefit), and numbered acceptance criteria. Optional notes capture constraints or dependencies.
+- Out of Scope, Assumptions, and Dependencies sections.
+
+Use stable references: `1` identifies Requirement 1; `1.2` identifies its second acceptance criterion. Preserve existing IDs when revising. Design and tasks use these same references.
+
+## EARS Acceptance Criteria
+
+Write specific, measurable outcomes with one behavior per criterion and unambiguous conditions.
+
+| Pattern | Form |
+|---------|------|
+| Ubiquitous | The system SHALL [behavior] |
+| Event-driven | WHEN [event] THEN the system SHALL [behavior] |
+| Conditional | IF [condition] THEN the system SHALL [behavior] |
+| Combined | WHEN [event] AND IF [condition] THEN the system SHALL [behavior] |
+| Optional | WHERE [feature included] the system SHALL [behavior] |
+
+Cover functional behavior, relevant performance/security/accessibility constraints, error and boundary cases, and success criteria. Keep scope explicit; propose a separate spec for unrelated expansion.
+
+Present the draft with a coverage summary and apply the [planning approval gate](../SKILL.md#core-contract).

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

@@ -0,0 +1,35 @@
+# Phase 3: Tasks
+
+Use approved requirements and design to create or update `tasks.md` in the active feature directory. Follow the [planning approval gate](../SKILL.md#core-contract).
+
+Initialize or preserve [lifecycle metadata](lifecycle-phase.md#metadata) when writing the plan.
+
+## Plan Contract
+
+Include a short implementation overview and groups of incremental coding tasks. Use at most two hierarchy levels: top-level groups and decimal task IDs such as `1.1`, `1.2`, `2.1`.
+
+Each task has a checkbox, unique number, action title, scope sub-bullets, and explicit [requirement/criterion references](requirements-phase.md#document-content). Enumerate IDs instead of using `All`, so task context and validation are bounded. Include relevant design section names in the scope when they are not evident from traceability.
+
+```markdown
+## 1. [Work group]
+
+- [ ] 1.1 [One logical implementation outcome]
+  - Depends on: none
+  - [Code to create or modify and integration points]
+  - [Tests or verification required by the design]
+  - _Requirements: 1.1, 1.2_
+```
+
+Tasks must be specific, testable, traceable, and small enough to validate individually. Order dependencies before dependent work, integrate code rather than leaving orphaned components, and include testing with test-driven development where appropriate.
+
+## Dependency Flow
+
+Every task declares `Depends on: none` or explicit prerequisite task IDs. These edges define the execution flow; list prerequisites before dependents and reject missing IDs, self-dependencies, and cycles before seeking plan approval. Dependencies refer to validated, integrated outcomes, not merely work started.
+
+For example, `1.1: none`, `1.2: 1.1`, `1.3: 1.1`, `1.4: 1.2, 1.3` means 1.1 first, then 1.2 and 1.3, then 1.4. Tasks 1.2 and 1.3 are dependency-independent and candidates for parallel execution under the [execution rules](execution-phase.md#parallel-execution-optional). Avoid maintaining a second ordering diagram.
+
+For older plans without dependency fields, retain listed sequential order and infer prerequisites conservatively from scope; missing fields do not mean independence. Clarify uncertainty before execution and add explicit dependencies through plan review before parallelizing.
+
+Exclude deployment, human acceptance/manual E2E testing, post-deployment metrics gathering, training, business-process changes, and marketing. Documentation tasks are allowed only when explicitly requested.
+
+Present the plan with its groups and task count for review. After approval, route execution requests to [Phase 4](execution-phase.md); execution scope and stopping rules live there and in the root contract.

package/skills/specflow/templates/project.md

@@ -0,0 +1,57 @@
+# Project Context
+
+## Tech Stack
+
+- **Language:** [e.g., TypeScript, Python, Java]
+- **Framework:** [e.g., Next.js, FastAPI, Spring Boot]
+- **Database:** [e.g., PostgreSQL, MongoDB, MySQL]
+- **Testing:** [e.g., Jest, pytest, JUnit]
+- **Build Tools:** [e.g., Vite, Webpack, Maven]
+
+## Coding Conventions
+
+- **Naming:** [e.g., camelCase for variables, PascalCase for classes]
+- **File Organization:** [e.g., feature-based folders, separation of concerns]
+- **Code Style:** [e.g., ESLint config, Prettier settings, PEP 8]
+- **Comments:** [e.g., JSDoc for public APIs, inline for complex logic]
+- **Error Handling:** [e.g., custom error classes, consistent error responses]
+
+## Architectural Patterns
+
+- **Architecture Style:** [e.g., Layered, Clean Architecture, Microservices]
+- **Design Patterns:** [e.g., Repository pattern, Factory pattern, Observer]
+- **State Management:** [e.g., Redux, Context API, Vuex]
+- **API Design:** [e.g., RESTful, GraphQL, gRPC]
+- **Data Flow:** [e.g., unidirectional data flow, event-driven]
+
+## Testing Standards
+
+- **Unit Tests:** [e.g., minimum 80% coverage, test pure functions]
+- **Integration Tests:** [e.g., test API endpoints, database interactions]
+- **Property-Based Tests:** [e.g., use fast-check/Hypothesis for core logic]
+- **Test Organization:** [e.g., co-located with source, separate test directory]
+- **Mocking Strategy:** [e.g., mock external services, use test databases]
+
+## Security Practices
+
+- **Authentication:** [e.g., JWT, OAuth 2.0, session-based]
+- **Authorization:** [e.g., RBAC, ABAC, permission middleware]
+- **Data Validation:** [e.g., input sanitization, schema validation]
+- **Secrets Management:** [e.g., environment variables, vault services]
+
+## Performance Guidelines
+
+- **Optimization:** [e.g., lazy loading, code splitting, caching strategies]
+- **Database:** [e.g., indexing strategy, query optimization, connection pooling]
+- **Monitoring:** [e.g., logging standards, metrics collection, alerting]
+
+## Related Documentation
+
+- [Link to architecture docs]
+- [Link to API documentation]
+- [Link to deployment guides]
+- [Link to team wiki]
+
+---
+
+**Instructions:** Fill in the sections above with your project-specific details. This file will be read by the AI assistant when creating and executing specs to ensure consistency across all features.

package/src/controller.test.ts

@@ -0,0 +1,195 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, rename, chmod } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SpecflowController } from "./controller.js";
+
+let root: string;
+let dir: string;
+
+/** Fixture writer: specs/<feature>/<file> relative to the specflow dir. */
+async function writeSpec(rel: string, content: string): Promise<string> {
+	const path = join(dir, rel);
+	await mkdir(join(path, ".."), { recursive: true });
+	await writeFile(path, content);
+	return path;
+}
+
+const TASKS_ACTIVE = ["---", "status: active", "---", "", "## Tasks", "", "- [ ] 1. Do the thing", "  - Criteria: AC1", "- [x] 2. Done thing", ""].join("\n");
+const REQUIREMENTS = "# Feature\n\n## Requirements\n\n- AC1: it works\n";
+
+function harness(intervalMs = 25) {
+	const updates: number[] = [];
+	const diagnostics: string[] = [];
+	const controller = new SpecflowController(dir, {
+		onUpdate: () => updates.push(updates.length + 1),
+		onDiagnostic: (m) => diagnostics.push(m),
+	}, intervalMs);
+	return { controller, updates, diagnostics };
+}
+
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+beforeEach(async () => {
+	root = await mkdtemp(join(tmpdir(), "specflow-ctl-"));
+	dir = join(root, ".specflow");
+});
+
+afterEach(async () => {
+	await rm(root, { recursive: true, force: true });
+});
+
+describe("SpecflowController.scan", () => {
+	test("a missing .specflow directory is not an error and yields no specs", async () => {
+		const { controller, diagnostics } = harness();
+		await controller.scan();
+		expect(controller.specs).toEqual([]);
+		expect(controller.active()).toBeUndefined();
+		expect(diagnostics).toEqual([]);
+	});
+
+	test("discovers flat and legacy specs and exposes the ranking winner", async () => {
+		await writeSpec("specs/active-flat/tasks.md", TASKS_ACTIVE);
+		// legacy layout: no frontmatter, status inferred from the containing directory
+		await writeSpec("specs/archived/older/tasks.md", "# Old\n");
+		const { controller } = harness();
+		await controller.scan();
+		expect(controller.specs.map((s) => s.name).sort()).toEqual(["active-flat", "older"]);
+		expect(controller.specs.find((s) => s.name === "older")?.status).toBe("archived");
+		// archived ranks below in-progress even though it is the newest on disk
+		expect(controller.active()?.name).toBe("active-flat");
+	});
+
+	test("a requirements-only spec is eligible", async () => {
+		await writeSpec("specs/req-only/requirements.md", REQUIREMENTS);
+		const { controller } = harness();
+		await controller.scan();
+		expect(controller.specs.map((s) => s.name)).toEqual(["req-only"]);
+	});
+
+	test("an unreadable tasks.md is reported once as a diagnostic, never thrown", async () => {
+		const path = await writeSpec("specs/broken/tasks.md", TASKS_ACTIVE);
+		await chmod(path, 0o000);
+		const { controller, diagnostics } = harness();
+		await controller.scan();
+		await controller.scan();
+		expect(controller.specs.map((s) => s.name)).toEqual(["broken"]);
+		expect(diagnostics.length).toBe(1); // reported once, not once per scan
+	});
+
+	test("an unreadable non-task document still lists the spec without a diagnostic", async () => {
+		// Discovery only needs tasks.md's content; requirements.md is read by the
+		// viewer, which reports the failure on open (AC4) instead of on every poll.
+		const path = await writeSpec("specs/quiet/requirements.md", REQUIREMENTS);
+		await writeSpec("specs/quiet/tasks.md", TASKS_ACTIVE);
+		await chmod(path, 0o000);
+		const { controller, diagnostics } = harness();
+		await controller.scan();
+		expect(controller.specs.map((s) => s.name)).toEqual(["quiet"]);
+		expect(diagnostics).toEqual([]);
+	});
+});
+
+describe("SpecflowController pinning", () => {
+	test("a pin survives refreshes but clears when the spec disappears", async () => {
+		await writeSpec("specs/one/tasks.md", TASKS_ACTIVE);
+		await writeSpec("specs/two/tasks.md", TASKS_ACTIVE);
+		const { controller } = harness();
+		await controller.scan();
+		const two = controller.specs.find((s) => s.name === "two");
+		controller.pin(two!.dir);
+		await controller.scan();
+		expect(controller.active()?.name).toBe("two");
+
+		await rm(join(dir, "specs/two"), { recursive: true, force: true });
+		await controller.scan();
+		expect(controller.pinned).toBeUndefined();
+		expect(controller.active()?.name).toBe("one");
+	});
+
+	test("hide and show are session-scoped state changes", async () => {
+		await writeSpec("specs/one/tasks.md", TASKS_ACTIVE);
+		const { controller } = harness();
+		await controller.scan();
+		expect(controller.hidden).toBe(false);
+		controller.hide();
+		expect(controller.hidden).toBe(true);
+		controller.show();
+		expect(controller.hidden).toBe(false);
+	});
+});
+
+describe("SpecflowController.onUpdate", () => {
+	test("fires only when the rendered content changes", async () => {
+		await writeSpec("specs/one/tasks.md", TASKS_ACTIVE);
+		const { controller, updates } = harness();
+		await controller.scan();
+		const afterFirst = updates.length;
+		await controller.scan(); // identical content
+		expect(updates.length).toBe(afterFirst);
+		controller.hide(); // visibility is part of the signature
+		expect(updates.length).toBe(afterFirst + 1);
+	});
+
+	test("fires when only the gate changes", async () => {
+		await writeSpec("specs/one/tasks.md", TASKS_ACTIVE);
+		const { controller, updates } = harness();
+		await controller.scan();
+		const before = updates.length;
+		await writeSpec("specs/one/tasks.md", TASKS_ACTIVE.replace("status: active", "status: active\ngate: review"));
+		await controller.scan();
+		expect(controller.active()?.gate).toBe("review");
+		expect(updates.length).toBe(before + 1);
+	});
+});
+
+describe("SpecflowController polling (AC6)", () => {
+	test("reflects a created spec, an atomic replace, and a deletion within a second", async () => {
+		const { controller } = harness(25);
+		await controller.scan();
+		controller.start();
+		try {
+			await writeSpec("specs/new/tasks.md", TASKS_ACTIVE);
+			await wait(400);
+			expect(controller.specs.map((s) => s.name)).toEqual(["new"]);
+
+			// atomic replace (write temp + rename over the target)
+			const target = join(dir, "specs/new/tasks.md");
+			const tmp = `${target}.tmp`;
+			await writeFile(tmp, TASKS_ACTIVE.replace("- [ ] 1. Do the thing", "- [x] 1. Do the thing"));
+			await rename(tmp, target);
+			await wait(400);
+			expect(controller.active()?.done).toBe(2);
+
+			await rm(join(dir, "specs/new/tasks.md"), { force: true });
+			await controller.scan();
+			expect(controller.specs).toEqual([]);
+		} finally {
+			controller.stop();
+		}
+	});
+
+	test("stop() halts polling and clears session state", async () => {
+		await writeSpec("specs/one/tasks.md", TASKS_ACTIVE);
+		const { controller } = harness(25);
+		await controller.scan();
+		controller.start();
+		await wait(60);
+		controller.stop();
+		expect(controller.specs).toEqual([]);
+		expect(controller.pinned).toBeUndefined();
+
+		await writeSpec("specs/late/tasks.md", TASKS_ACTIVE);
+		await wait(200);
+		expect(controller.specs).toEqual([]); // no ticks after stop
+	});
+
+	test("a scan started before stop() cannot apply its result", async () => {
+		await writeSpec("specs/one/tasks.md", TASKS_ACTIVE);
+		const { controller } = harness();
+		const pending = controller.scan();
+		controller.stop();
+		await pending;
+		expect(controller.specs).toEqual([]);
+	});
+});

package/src/controller.ts

@@ -0,0 +1,119 @@
+/**
+ * controller.ts — session-scoped state for the specflow panel: discovery
+ * polling, pinned selection, change/diagnostic dedup, and shutdown
+ * invalidation. Declared fork of speclet-tui/src/controller.ts (AC7);
+ * filesystem-free except through discoverSpecflows.
+ */
+
+import { discoverSpecflows, type SpecflowSpec } from "./parse.js";
+import { selectActive } from "./render.js";
+
+export interface ControllerHooks {
+	/** The rendered content of the active spec changed (or appeared/disappeared). */
+	onUpdate(): void;
+	/** A deduplicated diagnostic to surface (directory or read failure). */
+	onDiagnostic(message: string): void;
+}
+
+export class SpecflowController {
+	specs: SpecflowSpec[] = [];
+	/** Spec directory pinned via /specflow; cleared automatically when it disappears. */
+	pinned: string | undefined;
+	/** Panel visibility, toggled from the /specflow picker. Session-scoped. */
+	hidden = false;
+
+	private timer: ReturnType<typeof setTimeout> | undefined;
+	private generation = 0;
+	private lastSignature: string | undefined;
+	private lastDiagnostic: string | undefined;
+
+	constructor(
+		private readonly specflowDir: string,
+		private readonly hooks: ControllerHooks,
+		private readonly intervalMs = 500,
+	) {}
+
+	active(): SpecflowSpec | undefined {
+		return selectActive(this.specs, this.pinned);
+	}
+
+	pin(dir: string | undefined): void {
+		this.pinned = dir;
+		this.refreshSnapshot();
+	}
+
+	hide(): void {
+		this.hidden = true;
+		this.refreshSnapshot();
+	}
+
+	show(): void {
+		this.hidden = false;
+		this.refreshSnapshot();
+	}
+
+	/** Scan once now; safe to call directly (used by tests and start()). */
+	async scan(): Promise<void> {
+		const gen = this.generation;
+		const { specs, dirError } = await discoverSpecflows(this.specflowDir);
+		if (gen !== this.generation) return; // stale scan after shutdown
+
+		if (this.pinned !== undefined && !specs.some((s) => s.dir === this.pinned)) {
+			this.pinned = undefined; // pinned spec disappeared — back to ranking (AC1)
+		}
+		this.specs = specs;
+
+		const diagnostic =
+			dirError ?? (specs.filter((s) => s.error).map((s) => `${s.name}: ${s.error}`).join("; ") || undefined);
+		if (diagnostic !== this.lastDiagnostic) {
+			this.lastDiagnostic = diagnostic;
+			if (diagnostic) this.hooks.onDiagnostic(diagnostic);
+		}
+		this.refreshSnapshot();
+	}
+
+	/** Start the non-overlapping poll loop (AC6). */
+	start(): void {
+		void this.loop();
+	}
+
+	stop(): void {
+		this.generation++; // invalidates in-flight scans and scheduled ticks
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = undefined;
+		this.specs = [];
+		this.pinned = undefined;
+		this.hidden = false;
+	}
+
+	private async loop(): Promise<void> {
+		const gen = this.generation;
+		await this.scan();
+		if (gen !== this.generation) return;
+		this.timer = setTimeout(() => void this.loop(), this.intervalMs);
+	}
+
+	/** Fire onUpdate only when the rendered content of the active spec changed. */
+	private refreshSnapshot(): void {
+		const active = this.active();
+		const signature = JSON.stringify([
+			this.hidden,
+			active
+				? [
+						active.dir,
+						active.name,
+						active.status,
+						active.phase,
+						active.done,
+						active.total,
+						active.gate,
+						active.error ?? null,
+					]
+				: null,
+		]);
+		if (signature !== this.lastSignature) {
+			this.lastSignature = signature;
+			this.hooks.onUpdate();
+		}
+	}
+}