@alistigo/features 0.2.2

package/README.md

@@ -0,0 +1,101 @@
+# @alistigo/features
+
+Behavior specifications for Alistigo AI, written in [Gherkin](https://cucumber.io/docs/gherkin/reference/).
+
+These `.feature` files are the **source of truth for what the app should do**. The runner ([`@alistigo/features-runner-playwright`](../../cli/alistigo-features-runner-playwright/)) reads them and asserts the app conforms. We follow TDD — features are written and reviewed *before* the code that satisfies them.
+
+The package follows the universal conventions of the [`gherkin-features` skill](../../ai/skills/gherkin-features/SKILL.md). The skill is the source of truth for the structure (organization, tooling, tag categories, glossary sections); this package fills in the Alistigo-specific contents.
+
+## What lives here
+
+```
+packages/alistigo-features/
+├── features/                 # the .feature files (the actual specs)
+│   └── core/                 # one folder per FEATURE GROUP (mirrors @core tag)
+├── src/
+│   ├── index.ts              # exports FEATURES_DIR + tag types
+│   └── tags.ts               # the typed tag taxonomy (Milestone / Group / Capability / …)
+├── tools/
+│   └── validate.ts           # structural validator (taxonomy + parse + folder/group parity)
+├── docs/
+│   ├── organization.md       # how features are organized
+│   ├── style-guide.md        # how to write a feature
+│   ├── tags.md               # the tag taxonomy with descriptions
+│   └── glossary.md           # ubiquitous language: Entities / Actors / Actions
+├── .prettierrc.json          # Prettier (with prettier-plugin-gherkin)
+├── gherklin.config.ts        # Gherkin lint rules
+├── biome.json                # Biome config (extends root, ignores .feature)
+├── package.json
+└── project.json              # Nx targets
+```
+
+## Tooling
+
+| Tool | What it does | When it runs |
+|------|--------------|--------------|
+| [Prettier](https://prettier.io/) + [`prettier-plugin-gherkin`](https://www.npmjs.com/package/prettier-plugin-gherkin) | Formats `.feature` files (indentation, alignment, tag placement) | `pnpm format` / on save |
+| [Gherklin](https://github.com/cjmarkham/Gherklin) | Lints `.feature` files (structural rules, naming, duplicates, tag presence) | `pnpm nx qa:lint` |
+| `tools/validate.ts` (custom) | Parses every feature with `@cucumber/gherkin` and checks the **tag taxonomy** is respected | `pnpm validate` |
+| [Biome](https://biomejs.dev/) | Lints/formats TS/JS in this package only (ignores `features/`) | repo standard |
+
+Why this combination:
+- **Biome doesn't speak Gherkin** — Prettier + the gherkin plugin is the most-maintained option in 2026.
+- **Gherklin > older `gherkin-lint`** — modern TS/ESM, extensible, actively maintained.
+- The custom validator is a tiny TypeScript script that catches what the linter can't: tags that exist in files but aren't in the typed taxonomy. This keeps `src/tags.ts` and the actual `.feature` files in sync.
+
+## Conventions, in three places
+
+| If you want to know… | Read this |
+|----------------------|-----------|
+| **How features and folders are organized** | [docs/organization.md](docs/organization.md) |
+| **How to write a good Gherkin scenario** | [docs/style-guide.md](docs/style-guide.md) |
+| **What tags exist and what they mean** | [docs/tags.md](docs/tags.md) |
+| **What domain words mean (ubiquitous language)** | [docs/glossary.md](docs/glossary.md) |
+
+The tag taxonomy is also typed in [`src/tags.ts`](src/tags.ts). When you add or rename a tag, update *both* files — the validator enforces it.
+
+## Common Commands
+
+```sh
+pnpm format         # format all .feature files with Prettier
+pnpm format:check   # check formatting without writing
+pnpm nx qa:lint           # Biome (TS) + Gherklin (.feature)
+pnpm nx qa:lint:gherkin   # Gherklin only
+pnpm validate       # parse every .feature and check the tag taxonomy
+pnpm typecheck      # TypeScript check on src/ and tools/
+```
+
+Or via Nx from the repo root:
+
+```sh
+nx run alistigo-features:lint
+nx run alistigo-features:format
+nx run alistigo-features:validate
+```
+
+## Programmatic access
+
+```ts
+import { FEATURES_DIR, MILESTONE_TAGS, isKnownTag } from "@alistigo/features";
+
+// FEATURES_DIR is an absolute path — pass it to a runner.
+console.log(FEATURES_DIR);
+
+// MILESTONE_TAGS, CAPABILITY_TAGS, TEST_TYPE_TAGS, SUITE_TAGS, ACTOR_TAGS exported.
+console.log(MILESTONE_TAGS);  // ['@m1', '@m2', '@m3', '@m4', '@v1']
+
+// Validate a tag at runtime.
+isKnownTag("@m1");  // true
+isKnownTag("@made-up");  // false
+```
+
+## Contributing a feature
+
+See [docs/organization.md](docs/organization.md) and [docs/style-guide.md](docs/style-guide.md). In short:
+
+1. Pick the group folder (`features/core/`, or a plugin folder once those land).
+2. Name the file after the **capability** it covers, kebab-case (`add-element.feature`, `display-list.feature`).
+3. Tag the `Feature:` with exactly one milestone tag (`@m1` …), exactly one group tag matching the folder (`@core`), and one or more capability tags (`@capability:element` …).
+4. Use only words from [docs/glossary.md](docs/glossary.md) in step text.
+5. Write declarative scenarios (business language, not UI selectors).
+6. Run `pnpm format && pnpm nx qa:lint && pnpm validate` before committing.

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @alistigo/features
+ *
+ * Public surface of the package. Consumers (the runner, CI, anything that
+ * needs to enumerate or filter feature scenarios) import from here.
+ */
+export * from "./tags.js";
+/**
+ * Absolute path to the directory containing all `.feature` files in this
+ * package. Resolved relative to the published `dist/` so it works after build.
+ */
+export declare const FEATURES_DIR: string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,cAAc,WAAW,CAAC;AAE1B;;;GAGG;AACH,eAAO,MAAM,YAAY,QAIxB,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @alistigo/features
+ *
+ * Public surface of the package. Consumers (the runner, CI, anything that
+ * needs to enumerate or filter feature scenarios) import from here.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export * from "./tags.js";
+/**
+ * Absolute path to the directory containing all `.feature` files in this
+ * package. Resolved relative to the published `dist/` so it works after build.
+ */
+export const FEATURES_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "features");
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,cAAc,WAAW,CAAC;AAE1B;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CACtC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAC5C,IAAI,EACJ,UAAU,CACX,CAAC"}

package/dist/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@alistigo/features",
+  "version": "0.2.2",
+  "private": false,
+  "type": "module",
+  "description": "Gherkin behavior specifications for Alistigo AI. Source of truth for what the app should do; the runner reads these files to assert conformance.",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./tags": {
+      "import": "./dist/tags.js",
+      "types": "./dist/tags.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "features"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "gherklin": "^1.0.0",
+    "prettier": "^3.3.0",
+    "prettier-plugin-gherkin": "^3.1.2"
+  },
+  "module": "./index.js"
+}

package/dist/tags.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tag taxonomy for Alistigo feature files.
+ *
+ * This file is the **source of truth** for every tag the codebase recognizes.
+ * The Gherklin lint config references it; the runner uses it to filter
+ * scenarios; CI uses it to assemble suite runs.
+ *
+ * When you introduce a new tag, add it here AND document it in `docs/tags.md`.
+ * Untyped or undocumented tags are rejected by the lint pipeline.
+ *
+ * Tag categories follow the `gherkin-features` skill: Milestone, Group,
+ * Capability, Test type, Suite, Actor.
+ */
+/** Which milestone a feature belongs to. Required — every Feature has exactly one. */
+export declare const MILESTONE_TAGS: readonly ["@m1", "@m2", "@m3", "@m4", "@v1"];
+export type MilestoneTag = (typeof MILESTONE_TAGS)[number];
+/**
+ * Which feature group a feature belongs to. Required — every Feature has
+ * exactly one. Mirrors the folder layout under `features/`.
+ *
+ * - `@core` — base list app (text elements, add, delete, persist)
+ * - Plugin groups will be added as plugins land: `@todo`, `@checklist`, etc.
+ */
+export declare const GROUP_TAGS: readonly ["@core"];
+export type GroupTag = (typeof GROUP_TAGS)[number];
+/** What capability the feature exercises. Required — at least one. */
+export declare const CAPABILITY_TAGS: readonly ["@capability:list", "@capability:element", "@capability:persistence", "@capability:loading", "@capability:export", "@capability:host-protocol", "@capability:plugins"];
+export type CapabilityTag = (typeof CAPABILITY_TAGS)[number];
+/** What kind of scenario this is. Optional. */
+export declare const TEST_TYPE_TAGS: readonly ["@happy-path", "@edge-case", "@error-path"];
+export type TestTypeTag = (typeof TEST_TYPE_TAGS)[number];
+/** Which suite the scenario participates in. Optional. */
+export declare const SUITE_TAGS: readonly ["@smoke", "@regression", "@todo"];
+export type SuiteTag = (typeof SUITE_TAGS)[number];
+/** Who triggers the scenario. Optional. */
+export declare const ACTOR_TAGS: readonly ["@actor:user", "@actor:ai", "@actor:host"];
+export type ActorTag = (typeof ACTOR_TAGS)[number];
+export type AlistigoTag = MilestoneTag | GroupTag | CapabilityTag | TestTypeTag | SuiteTag | ActorTag;
+export declare const ALL_TAGS: readonly AlistigoTag[];
+/** True if the tag is part of the recognized taxonomy. */
+export declare function isKnownTag(tag: string): tag is AlistigoTag;
+//# sourceMappingURL=tags.d.ts.map

package/dist/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,sFAAsF;AACtF,eAAO,MAAM,cAAc,8CAA+C,CAAC;AAC3E,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,oBAAqB,CAAC;AAC7C,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,sEAAsE;AACtE,eAAO,MAAM,eAAe,kLAQlB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,+CAA+C;AAC/C,eAAO,MAAM,cAAc,uDAAwD,CAAC;AACpF,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,0DAA0D;AAC1D,eAAO,MAAM,UAAU,6CAA8C,CAAC;AACtE,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,2CAA2C;AAC3C,eAAO,MAAM,UAAU,sDAAuD,CAAC;AAC/E,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,MAAM,MAAM,WAAW,GACnB,YAAY,GACZ,QAAQ,GACR,aAAa,GACb,WAAW,GACX,QAAQ,GACR,QAAQ,CAAC;AAEb,eAAO,MAAM,QAAQ,EAAE,SAAS,WAAW,EAO1C,CAAC;AAIF,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,WAAW,CAE1D"}

package/dist/tags.js

@@ -0,0 +1,53 @@
+/**
+ * Tag taxonomy for Alistigo feature files.
+ *
+ * This file is the **source of truth** for every tag the codebase recognizes.
+ * The Gherklin lint config references it; the runner uses it to filter
+ * scenarios; CI uses it to assemble suite runs.
+ *
+ * When you introduce a new tag, add it here AND document it in `docs/tags.md`.
+ * Untyped or undocumented tags are rejected by the lint pipeline.
+ *
+ * Tag categories follow the `gherkin-features` skill: Milestone, Group,
+ * Capability, Test type, Suite, Actor.
+ */
+/** Which milestone a feature belongs to. Required — every Feature has exactly one. */
+export const MILESTONE_TAGS = ["@m1", "@m2", "@m3", "@m4", "@v1"];
+/**
+ * Which feature group a feature belongs to. Required — every Feature has
+ * exactly one. Mirrors the folder layout under `features/`.
+ *
+ * - `@core` — base list app (text elements, add, delete, persist)
+ * - Plugin groups will be added as plugins land: `@todo`, `@checklist`, etc.
+ */
+export const GROUP_TAGS = ["@core"];
+/** What capability the feature exercises. Required — at least one. */
+export const CAPABILITY_TAGS = [
+    "@capability:list",
+    "@capability:element",
+    "@capability:persistence",
+    "@capability:loading",
+    "@capability:export",
+    "@capability:host-protocol",
+    "@capability:plugins",
+];
+/** What kind of scenario this is. Optional. */
+export const TEST_TYPE_TAGS = ["@happy-path", "@edge-case", "@error-path"];
+/** Which suite the scenario participates in. Optional. */
+export const SUITE_TAGS = ["@smoke", "@regression", "@todo"];
+/** Who triggers the scenario. Optional. */
+export const ACTOR_TAGS = ["@actor:user", "@actor:ai", "@actor:host"];
+export const ALL_TAGS = [
+    ...MILESTONE_TAGS,
+    ...GROUP_TAGS,
+    ...CAPABILITY_TAGS,
+    ...TEST_TYPE_TAGS,
+    ...SUITE_TAGS,
+    ...ACTOR_TAGS,
+];
+const TAG_SET = new Set(ALL_TAGS);
+/** True if the tag is part of the recognized taxonomy. */
+export function isKnownTag(tag) {
+    return TAG_SET.has(tag);
+}
+//# sourceMappingURL=tags.js.map

package/dist/tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../src/tags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAU,CAAC;AAG3E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAO,CAAU,CAAC;AAG7C,sEAAsE;AACtE,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,kBAAkB;IAClB,qBAAqB;IACrB,yBAAyB;IACzB,qBAAqB;IACrB,oBAAoB;IACpB,2BAA2B;IAC3B,qBAAqB;CACb,CAAC;AAGX,+CAA+C;AAC/C,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,aAAa,EAAE,YAAY,EAAE,aAAa,CAAU,CAAC;AAGpF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,CAAU,CAAC;AAGtE,2CAA2C;AAC3C,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,aAAa,EAAE,WAAW,EAAE,aAAa,CAAU,CAAC;AAW/E,MAAM,CAAC,MAAM,QAAQ,GAA2B;IAC9C,GAAG,cAAc;IACjB,GAAG,UAAU;IACb,GAAG,eAAe;IAClB,GAAG,cAAc;IACjB,GAAG,UAAU;IACb,GAAG,UAAU;CACd,CAAC;AAEF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,QAAQ,CAAC,CAAC;AAE1C,0DAA0D;AAC1D,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC"}

package/features/core/README.md

@@ -0,0 +1,36 @@
+# core — Base list app
+
+The foundational feature group for Alistigo AI. Every list type the project will ever support (todo, checklist, grocery, wishlist, …) is built **on top of** the core list app via plugins.
+
+These features describe what the **base list** does — without any plugin loaded.
+
+| File | Capability |
+|------|------------|
+| [display-list.feature](display-list.feature) | Render the list (empty, populated, with duplicates) |
+| [add-element.feature](add-element.feature) | Append a text element |
+| [delete-element.feature](delete-element.feature) | Remove an element by identity (or by row when duplicates collide) |
+| [persist.feature](persist.feature) | Survive a reload |
+
+## Scope
+
+The base list:
+
+- holds a sequence of **text elements** — nothing else (no checkbox, no priority, no due date — those are plugin behaviors)
+- has an **internal order** that is preserved on read but **NOT displayed** to the user (the user sees rows; positions are not shown)
+- supports **add** and **delete**
+- **allows duplicates** — two elements with the same text are two distinct elements with distinct identities
+
+What's deliberately out of scope at this layer:
+- Completion / checkbox state → todo plugin (later)
+- Sorting, ordered display → ordering plugin (later)
+- Editing element text → edit plugin (later)
+- Categories, priorities, dates, images → respective plugins (later)
+
+## Definition of Done
+
+The base list (and its M1 milestone) is done when every scenario in this folder is green via the runner *and* replaying the event log produces the same projection.
+
+See:
+- [`projects/alistigo-ai/milestones.md`](../../../../projects/alistigo-ai/milestones.md) for the milestone roadmap
+- [`docs/glossary.md`](../../docs/glossary.md) for the entities, actors, and actions that may appear in step text
+- [`docs/style-guide.md`](../../docs/style-guide.md) for how to write a scenario

package/features/core/add-element.feature

@@ -0,0 +1,33 @@
+@m1
+@core
+@capability:element
+@actor:user
+Feature: Add an element to a list
+  As a User
+  I want to add a text element to the list
+  So that I can capture something into it
+
+  @happy-path
+  @smoke
+  Scenario: Add to an empty list
+    Given an empty list
+    When I add "Buy bread"
+    Then the list should be:
+      | Buy bread |
+
+  @happy-path
+  Scenario: Add to a populated list
+    Given a list:
+      | Buy bread |
+    When I add "Call mom"
+    Then the list should be:
+      | Buy bread |
+      | Call mom  |
+
+  Scenario: Add an element with the same text as an existing one
+    Given a list:
+      | Buy bread |
+    When I add "Buy bread"
+    Then the list should be:
+      | Buy bread |
+      | Buy bread |

package/features/core/delete-element.feature

@@ -0,0 +1,35 @@
+@m1
+@core
+@capability:element
+@actor:user
+Feature: Delete an element from a list
+  As a User
+  I want to remove an element
+  So that the list reflects only what I still care about
+
+  @happy-path
+  @smoke
+  Scenario: Delete the only element of a list
+    Given a list:
+      | Buy bread |
+    When I delete "Buy bread"
+    Then the list should be empty
+
+  @happy-path
+  Scenario: Delete from a populated list
+    Given a list:
+      | Buy bread |
+      | Call mom  |
+    When I delete "Buy bread"
+    Then the list should be:
+      | Call mom |
+
+  Scenario: Delete one occurrence of a duplicate
+    Given a list:
+      | Buy bread |
+      | Call mom  |
+      | Buy bread |
+    When I delete row 1
+    Then the list should be:
+      | Call mom  |
+      | Buy bread |

package/features/core/display-list.feature

@@ -0,0 +1,37 @@
+@m1
+@core
+@capability:list
+@capability:loading
+Feature: Display a list
+  As a User opening the list
+  I want to see all elements of the list
+  So that I know what is in it
+
+  @happy-path
+  @smoke
+  Scenario: An empty list shows an empty state
+    Given an empty list
+    When I open the list
+    Then the list should be empty
+    And an empty-state message should be visible
+
+  @happy-path
+  Scenario: A populated list shows every element
+    Given a list:
+      | Buy bread |
+      | Call mom  |
+    When I open the list
+    Then the list should be:
+      | Buy bread |
+      | Call mom  |
+
+  Scenario: Duplicate text appears as separate elements
+    Given a list:
+      | Buy bread |
+      | Call mom  |
+      | Buy bread |
+    When I open the list
+    Then the list should be:
+      | Buy bread |
+      | Call mom  |
+      | Buy bread |

package/features/core/persist.feature

@@ -0,0 +1,27 @@
+@m1
+@core
+@capability:persistence
+Feature: Persist a list across reloads
+  As a User
+  I want my list to survive a reload
+  So that I do not lose its content when the list is reopened
+
+  @happy-path
+  @smoke
+  Scenario: An added element is still there after a reload
+    Given an empty list
+    When I add "Buy bread"
+    And I reload the list
+    Then the list should be:
+      | Buy bread |
+
+  @happy-path
+  @smoke
+  Scenario: A deleted element stays deleted after a reload
+    Given a list:
+      | Buy bread |
+      | Call mom  |
+    When I delete "Buy bread"
+    And I reload the list
+    Then the list should be:
+      | Call mom |

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@alistigo/features",
+  "version": "0.2.2",
+  "private": false,
+  "type": "module",
+  "description": "Gherkin behavior specifications for Alistigo AI. Source of truth for what the app should do; the runner reads these files to assert conformance.",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./tags": {
+      "import": "./dist/tags.js",
+      "types": "./dist/tags.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "features"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "gherklin": "^1.0.0",
+    "prettier": "^3.3.0",
+    "prettier-plugin-gherkin": "^3.1.2"
+  }
+}