@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-feature-status/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: fluent-feature-status
+description: Dashboard view of all features and their lifecycle status. Scans accounts/<PROFILE>/features/*/status.json and presents a consolidated table with filtering, sorting, and workspace tree view. Triggers on "feature status", "show features", "what features", "feature dashboard", "where am I", "what's in progress".
+user-invocable: true
+allowed-tools: Bash, Read, Glob, Grep
+argument-hint: [--profile PROFILE] [--filter STATUS] [--format table|json] [--tree]
+---
+
+# Feature Status Dashboard
+
+Scan all feature directories for a profile and present a unified dashboard showing lifecycle status, next actions, and workspace health. This is the "where am I?" view that answers "what features exist, what state are they in, and what should I do next?"
+
+## Ownership Boundary
+
+This skill owns: feature status aggregation, dashboard rendering, workspace tree view, resume recommendations.
+
+Other skills own: individual feature lifecycle transitions (`/fluent-use-case-discover`, `/fluent-feature-plan`, `/fluent-archive`, etc.), session audit trail (`/fluent-session-summary`).
+
+## When to Use
+
+- **Session start** — see where you left off across all features
+- **After completing a major step** — verify status updated correctly
+- **Managing multiple features** — get the big picture at a glance
+- **Before archival** — identify features ready to archive (VERIFIED status)
+- **Onboarding to a workspace** — understand what's been built
+- **Progress check** — during multi-feature work, see the full picture
+
+## No Planning Gate
+
+This is a **read-only** diagnostic skill. No planning gate required. It can be invoked at any time without approval, writes no files, and makes no mutations.
+
+## Inputs
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `--profile` | No | Active CLI profile (or all profiles) | Fluent CLI profile to scan |
+| `--filter` | No | (all statuses) | Filter by status: `DISCOVERY`, `PLANNING`, `APPROVED`, `IN_PROGRESS`, `VERIFIED`, `ARCHIVED` |
+| `--format` | No | `table` | Output format: `table` (human-readable) or `json` (machine-readable) |
+| `--tree` | No | `false` | Also show workspace directory tree with artifact counts |
+
+## Execution Flow
+
+```
+1. RESOLVE profile
+   - From --profile arg, or active Fluent CLI profile, or scan all profiles
+   - Validate accounts/<PROFILE>/ directory exists
+
+2. SCAN feature directories
+   - Glob: accounts/<PROFILE>/features/*/status.json
+   - If no --profile: accounts/*/features/*/status.json
+   - If no features/ directory -> report "No features found" with guidance
+
+3. PARSE each status.json
+   - Validate $schema = "feature-status-v1"
+   - Extract all fields: feature, retailers (or retailer), status, spec, plan,
+     planRevision, architecture, basedOn, next, updated
+   - On parse error -> add to warnings list, include with status PARSE_ERROR
+
+4. SORT features
+   - Primary: status priority (IN_PROGRESS > APPROVED > PLANNING > DISCOVERY > VERIFIED > ARCHIVED)
+   - Secondary: updated date descending (most recent first)
+
+5. FILTER (if --filter specified)
+   - Keep only features matching the requested status
+   - Case-insensitive comparison
+
+6. DETECT attention flags
+   - STALE: IN_PROGRESS + updated > 7 days ago
+   - ready to build: APPROVED + no build/deploy reports
+   - awaiting spec approval: PLANNING + spec not APPROVED
+   - awaiting plan approval: PLANNING + spec APPROVED + plan not APPROVED
+
+7. RENDER output
+   - table: formatted markdown table with summary footer + recommendation
+   - json: structured JSON with features array and summary object
+
+8. RECOMMEND next action
+   - If any STALE feature -> "Resume: ..."
+   - If any IN_PROGRESS feature -> "Continue: ..."
+   - If any APPROVED feature -> "Start building: ..."
+   - If all VERIFIED/ARCHIVED -> "All features complete."
+```
+
+## Status Priority Order
+
+Features are sorted by lifecycle urgency -- active work first, historical last.
+
+| Priority | Status | Meaning |
+|----------|--------|---------|
+| 1 | `IN_PROGRESS` | Active work -- resume this first |
+| 2 | `APPROVED` | Ready to start building |
+| 3 | `PLANNING` | Needs plan review/approval |
+| 4 | `DISCOVERY` | Early stage -- spec in progress |
+| 5 | `VERIFIED` | Complete -- ready to archive |
+| 6 | `ARCHIVED` | Historical reference |
+
+## Dashboard Table Format
+
+```
+=== Feature Dashboard: HMDEV ===
+
+| Feature           | Retailers    | Status        | Spec     | Plan (Rev) | Arch | Next                      | Updated    |
+|-------------------|--------------|---------------|----------|------------|------|---------------------------|------------|
+| order-return      | HM_TEST      | IN_PROGRESS   | APPROVED | APPROVED (v1) | Yes | /fluent-build          | 2026-02-25 |
+| curbside-pickup   | Module Test  | APPROVED      | APPROVED | APPROVED (v2) | Yes | /fluent-rule-scaffold  | 2026-02-24 |
+| click-collect     | Module Test  | PLANNING      | APPROVED | PENDING    | No   | awaiting plan approval    | 2026-02-25 |
+| returns-flow      | Module Test  | DISCOVERY     | DRAFT    | --         | No   | /fluent-use-case-discover | 2026-02-25 |
+
+Summary: 4 features (1 IN_PROGRESS, 1 APPROVED, 1 PLANNING, 1 DISCOVERY)
+
+Recommendation: Continue /fluent-build on "order-return"
+```
+
+### Attention Flags
+
+| Condition | Flag | Rendering |
+|-----------|------|-----------|
+| IN_PROGRESS + updated > 7 days ago | STALE | Status shows "IN_PROGRESS (STALE)" |
+| APPROVED + no implementation evidence | ready to build | Highlighted in recommendation |
+| PLANNING + spec not APPROVED | awaiting spec | Next shows "awaiting spec approval" |
+| PLANNING + spec APPROVED + plan not APPROVED | awaiting plan | Next shows "awaiting plan approval" |
+| Has `basedOn` field | basedOn: slug | Arch column shows "Yes (basedOn: slug)" |
+
+### Column Definitions
+
+| Column | Source | Notes |
+|--------|--------|-------|
+| Feature | `feature` field | Slug (matches directory name) |
+| Retailers | `retailers[]` or `retailer` | Comma-separated if multiple; `--` if null |
+| Status | `status` field | With attention flags appended |
+| Spec | `spec` field | DRAFT / APPROVED / `--` |
+| Plan (Rev) | `plan` + `planRevision` | e.g., "APPROVED (v2)" or "PENDING" or `--` |
+| Arch | `architecture` field | Yes / No; "(basedOn: X)" if basedOn field set |
+| Next | `next` field or derived | Advisory next skill or attention flag |
+| Updated | `updated` field | Last modification date |
+
+## JSON Output Format
+
+When `--format json`:
+
+```json
+{
+  "profile": "HMDEV",
+  "scannedAt": "2026-02-25T10:00:00Z",
+  "features": [
+    {
+      "slug": "order-return",
+      "retailers": ["HM_TEST"],
+      "status": "IN_PROGRESS",
+      "spec": "APPROVED",
+      "plan": "APPROVED",
+      "planRevision": 1,
+      "architecture": true,
+      "basedOn": null,
+      "next": "/fluent-build",
+      "updated": "2026-02-25",
+      "path": "accounts/HMDEV/features/order-return/",
+      "flags": []
+    },
+    {
+      "slug": "curbside-pickup",
+      "retailers": ["Module Test"],
+      "status": "APPROVED",
+      "spec": "APPROVED",
+      "plan": "APPROVED",
+      "planRevision": 2,
+      "architecture": true,
+      "basedOn": null,
+      "next": "/fluent-rule-scaffold",
+      "updated": "2026-02-24",
+      "path": "accounts/HMDEV/features/curbside-pickup/",
+      "flags": ["ready_to_build"]
+    }
+  ],
+  "summary": {
+    "total": 4,
+    "byStatus": {
+      "IN_PROGRESS": 1,
+      "APPROVED": 1,
+      "PLANNING": 1,
+      "DISCOVERY": 1
+    },
+    "stale": 0
+  },
+  "recommendation": "Continue /fluent-build on \"order-return\"",
+  "warnings": []
+}
+```
+
+## Workspace Tree View (--tree)
+
+When `--tree` is specified, scan and render the full workspace structure:
+
+```
+=== Workspace: HMDEV ===
+
+accounts/HMDEV/
++-- features/                        (4 features)
+|   +-- order-return/                (IN_PROGRESS -> /fluent-build)
+|   +-- curbside-pickup/             (APPROVED -> /fluent-rule-scaffold)
+|   +-- click-collect/               (PLANNING -> awaiting plan approval)
+|   +-- returns-flow/                (DISCOVERY -> /fluent-use-case-discover)
++-- SOURCE/                          (2 repos)
+|   +-- fc-module-hm-ext/            (module.json: 12 rules)
+|   +-- fc-module-returns/           (module.json: 5 rules)
++-- workflows/
+|   +-- HM_TEST/                     (8 workflow files)
++-- reports/
+|   +-- build/                       (2 reports)
+|   +-- pre-deploy/                  (1 report)
+|   +-- e2e-test/                    (0 reports)
++-- analysis/
+|   +-- code/                        (3 files)
+|   +-- topology/                    (1 file)
+|   +-- settings/                    (0 files)
++-- tasks/                           (2 task plans)
++-- sessions/                        (5 exports)
+```
+
+### Tree Artifact Counting
+
+| Directory | Count Method |
+|-----------|-------------|
+| `features/*/` | Glob for `status.json` files |
+| `SOURCE/*/` | Glob for `module.json` files; count rules from each |
+| `workflows/RETAILER/` | Count `*.json` excluding `workflow-context.json` |
+| `reports/*/` | Count files per subdirectory |
+| `analysis/*/` | Count files per subdirectory |
+| `tasks/` | Count `*.md` files |
+| `sessions/` | Count `*.json` files |
+
+## Multi-Profile View
+
+When no `--profile` is specified and multiple profiles have features:
+
+```
+=== Feature Dashboard ===
+
+### HMDEV (3 features)
+| Feature | Retailers | Status | ... |
+...
+
+### SAGIRISH (2 features)
+| Feature | Retailers | Status | ... |
+...
+
+Overall: 5 features across 2 profiles (2 IN_PROGRESS, 1 APPROVED, 2 PLANNING)
+```
+
+## Edge Cases
+
+### No features directory
+```
+No features found for profile HMDEV.
+Start with: /fluent-use-case-discover to define your first feature.
+```
+
+### Empty features directory
+Same message as above.
+
+### Malformed status.json
+```
+Warnings:
+  features/broken-feature/status.json: Invalid JSON (unexpected token at line 5)
+  features/old-feature/status.json: Missing required field "status"
+```
+
+Include in table with status `PARSE_ERROR`. Do not skip -- visibility matters.
+
+### Missing fields in status.json
+Use `--` for any missing optional field. Required fields (`feature`, `status`) trigger a warning.
+
+### Backward compatibility
+If `retailers` array is absent but `retailer` (string) exists, treat as `["retailer-value"]`. If both exist, prefer `retailers`.
+
+### Archived features
+Include at bottom of table. Exclude from summary counts by default. Show separately: "Plus 2 archived features (use --filter ARCHIVED to view)".
+
+## Handoff Protocol
+
+### Emitted Signals
+- `-> READY: accounts/PROFILE/features/` -- Dashboard rendered successfully
+- `-> NEXT: /fluent-<next-skill> --feature "slug"` -- Recommend resuming highest-priority feature (skill name from status.json `next` field)
+- `-> SKIP: No features found` -- Empty workspace, suggest /fluent-use-case-discover
+
+### Consumed Signals
+This skill does not consume handoff signals -- it reads `status.json` files directly.
+
+## Error Reporting
+
+| Severity | Code | Scenario | Recovery |
+|----------|------|----------|----------|
+| LOW | `PARSE_WARNING` | Malformed status.json | Skip feature, show warning |
+| LOW | `MISSING_FIELD` | Optional field missing | Display as `--` |
+| MEDIUM | `NO_FEATURES` | No feature directories found | Guide to /fluent-use-case-discover |
+| MEDIUM | `PROFILE_NOT_FOUND` | Profile directory does not exist | Guide to /fluent-connect |
+
+## Session Tracking
+
+When invoked, log:
+```
+SKILL: /fluent-feature-status
+  args: [--profile PROFILE] [--filter STATUS] [--format FORMAT] [--tree]
+  outcome: completed | failed
+  features_found: count
+  features_by_status: { "IN_PROGRESS": 1, "APPROVED": 2, ... }
+  stale_count: count
+  warnings: count
+  recommendation: "next action"
+```
+
+## Integration with Other Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `/fluent-use-case-discover` | Creates features in DISCOVERY status |
+| `/fluent-feature-plan` | Moves features to PLANNING then APPROVED |
+| `/fluent-feature-explain` | Sets `architecture: true` |
+| `/fluent-archive` | Moves features to ARCHIVED |
+| `/fluent-rollback` | May regress feature status after deployment rollback |
+| `/fluent-session-summary` | Complementary -- session changes vs feature lifecycle |
+| `/fluent-scope-decompose` | Can batch-create features via `--batch-features` |
+
+## Tips
+
+- Run this at the **start of every session** to orient yourself
+- Use `--filter IN_PROGRESS` to focus on active work
+- Use `--filter APPROVED` to find features ready to build
+- The `next` field tells you exactly which skill to invoke next
+- Combine with `/fluent-session-summary` for a complete picture
+- Use `--tree` when onboarding to a workspace to see everything
+- The JSON output (`--format json`) is useful for scripting
+- Features are sorted by priority -- first row is always the most urgent
+- STALE flag warns about features that may have been forgotten
+- Archived features are hidden by default -- use `--filter ARCHIVED` to see them

package/content/dev/skills/fluent-feedback/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: fluent-feedback
+description: View, review, and promote skill execution feedback. Dashboard shows per-skill success/failure rates, recurring issues, and learnings ready for promotion. Triggers on "feedback dashboard", "show feedback", "review feedback", "promote learning", "skill feedback", "what went wrong".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: dashboard | review <skill-name> | promote <record-id> | export [--format json|confluence]
+---
+
+# Skill Feedback Manager
+
+View, analyze, and promote feedback records captured during skill execution. Feedback records are written by skills after each execution (see Feedback Loop Protocol) and stored as JSONL files in `accounts/<PROFILE>/feedback/`.
+
+## Commands
+
+### `dashboard` (default)
+
+Show per-skill feedback summary for the current profile.
+
+**Steps:**
+
+1. Determine `<PROFILE>` from the active Fluent CLI profile or ask the user
+2. Check if `accounts/<PROFILE>/feedback/index.json` exists
+3. If yes, read it and display summary table
+4. If no, scan for any `.jsonl` files in `accounts/<PROFILE>/feedback/` and rebuild index
+5. If no feedback directory exists, report "No feedback captured yet" and explain how feedback gets generated
+
+**Output format:**
+
+```
+Skill Feedback Dashboard — <PROFILE>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Skill                  │ Total │  OK │ FAIL │ Corrected │ Top Issue
+───────────────────────┼───────┼─────┼──────┼───────────┼──────────────────
+workflow-builder       │   17  │  12 │   3  │     2     │ Ghost categories
+workflow-deploy        │   13  │   8 │   4  │     1     │ POST vs PUT
+settings               │    8  │   5 │   2  │     1     │ Missing context
+rule-scaffold          │    7  │   6 │   1  │     0     │ —
+
+Recurring issues (3+ occurrences):
+  1. UNUSED_CATEGORY_FOUND — 5 hits ← READY TO PROMOTE
+  2. Wrong REST method — 3 hits ← READY TO PROMOTE
+```
+
+### `review <skill-name>`
+
+Show all feedback records for a specific skill, grouped by outcome.
+
+**Steps:**
+
+1. Read `accounts/<PROFILE>/feedback/<skill-name>.jsonl`
+2. Parse each line as JSON
+3. Group by outcome: FAILURE and USER_CORRECTED first (most actionable)
+4. For each record, show: timestamp, outcome, feature, phases summary, learnings
+5. Highlight records with `confidence: "CONFIRMED"` that have 3+ occurrences — flag as "ready to promote"
+6. Show user corrections prominently — these are the highest-signal feedback
+
+**Output format per record:**
+
+```
+[2026-02-24 14:30] PARTIAL_SUCCESS — curbside-pickup (ORDER::HD)
+  Phases: pre-flight ✓ → build-rulesets ✓ → deploy ✗ (UNUSED_CATEGORY_FOUND)
+  Resolution: Added explicit category to all statuses
+  Learning: "Never use empty string for status categories" [CONFIRMED, 5 hits]
+  ← READY TO PROMOTE
+```
+
+### `promote <record-id>`
+
+Promote a confirmed learning into a skill's Known Pitfalls section.
+
+**Promotion guardrails (ALL must pass):**
+
+1. Learning must have evidence from **3+ distinct sessions** (check `id` prefixes for different dates/times)
+2. At least one `USER_CORRECTED` record exists for this learning, OR user explicitly says "promote this"
+3. Learning text is **generic and portable** — not account-specific, not retailer-secret, not environment-only
+4. If any guardrail fails: keep at `CONFIRMED`, explain why, suggest how to meet the threshold
+
+**If guardrails pass:**
+
+1. Read the target `SKILL.md` file for the skill referenced in the learning
+2. Find or create the `## Known Pitfalls` section
+3. Find or create the `<!-- feedback-promoted: managed section -->` block
+4. Append the learning in format:
+   ```
+   - **<ERROR_CODE>** — <learning text>.
+     _Source: <N> feedback records, first seen <date>, promoted <today>_
+   ```
+5. Write a promotion record to `.fluent-ai-skills/feedback/promotions.jsonl`:
+   ```json
+   {"promotedAt":"<ISO>","skill":"<name>","learning":"<text>","evidence":["<id1>","<id2>","<id3>"],"promotedBy":"user","section":"Known Pitfalls"}
+   ```
+6. Update the original feedback records: set `confidence` from `CONFIRMED` to `PROMOTED`
+
+### `export [--format json|confluence]`
+
+Export feedback for team sharing.
+
+**JSON format (default):** Writes all `.jsonl` files to a single `accounts/<PROFILE>/feedback/export-<date>.json` with structure:
+```json
+{
+  "profile": "<PROFILE>",
+  "exportedAt": "<ISO>",
+  "skills": {
+    "<skill-name>": [ ...records... ]
+  }
+}
+```
+
+**Confluence format:** Generates a wiki-markup table suitable for pasting into Confluence:
+```
+|| Skill || Issue || Occurrences || Confidence || Learning ||
+| workflow-builder | UNUSED_CATEGORY_FOUND | 5 | CONFIRMED | Never use empty string for categories |
+```
+
+Write to `accounts/<PROFILE>/feedback/export-<date>.wiki` or `.json`.
+
+## Feedback Record Schema (feedback-record-v1)
+
+Reference schema for records written by other skills. This skill reads them; other skills write them.
+
+```jsonc
+{
+  "$schema": "feedback-record-v1",
+  "id": "fb-<YYYYMMDD>-<HHMMSS>-<3char>",   // unique, sortable
+  "timestamp": "<ISO-8601>",
+  "skill": "<skill-name>",                    // which skill produced this
+  "feature": "<slug>",                        // feature slug if applicable, null otherwise
+  "profile": "<PROFILE>",
+  "retailer": "<retailer-name>",
+  "entityType": "<ORDER|FULFILMENT|...>",     // primary entity, null if N/A
+  "entitySubtype": "<HD|CC|...>",             // subtype, null if N/A
+
+  "outcome": "<SUCCESS|PARTIAL_SUCCESS|FAILURE|BLOCKED|USER_CORRECTED>",
+
+  "phases": [
+    {
+      "name": "<phase-name>",                 // e.g., "pre-flight-check", "build-rulesets", "deploy"
+      "status": "<PASS|FAIL|SKIP>",
+      "error": "<error-code>",               // only if FAIL
+      "errorDetail": "<human-readable>",      // only if FAIL
+      "resolution": "<what-fixed-it>"         // only if FAIL then resolved
+    }
+  ],
+
+  "learnings": [
+    {
+      "type": "<GOTCHA|PATTERN|CORRECTION|WORKAROUND|CONSTRAINT>",
+      "scope": "<platform|account|feature>",
+      "skill": "<target-skill>",              // which skill should learn this
+      "text": "<learning text>",
+      "confidence": "<OBSERVED|CONFIRMED|PROMOTED>",
+      "tags": ["<tag1>", "<tag2>"],
+      "relatedError": "<error-code>"          // for pattern matching
+    }
+  ],
+
+  "userCorrections": [
+    {
+      "what": "<what-agent-did-wrong>",
+      "correction": "<what-user-said>",
+      "impact": "<HIGH|MEDIUM|LOW>"
+    }
+  ],
+
+  "tags": ["<tag1>", "<tag2>"],
+  "planRef": "<path-to-plan-if-applicable>"
+}
+```
+
+### Secret redaction rules
+
+Before writing any feedback record, redact:
+- `accessToken`, `clientSecret`, `password`, API keys, bearer tokens
+- Any value matching patterns: `eyJ...` (JWT), `sk-...`, `token=...`
+
+**Keep** (needed for retrieval filtering): profile name, retailer ref, entity refs, order refs, setting names, workflow names.
+
+## Index Schema
+
+`accounts/<PROFILE>/feedback/index.json`:
+
+```json
+{
+  "$schema": "feedback-index-v1",
+  "profile": "<PROFILE>",
+  "lastUpdated": "<ISO-8601>",
+  "skills": {
+    "<skill-name>": {
+      "total": 17,
+      "success": 12,
+      "partialSuccess": 2,
+      "failure": 3,
+      "blocked": 0,
+      "userCorrected": 2,
+      "lastUpdated": "<ISO-8601>",
+      "topIssue": "UNUSED_CATEGORY_FOUND",
+      "topIssueSeverity": "HIGH"
+    }
+  }
+}
+```
+
+## Rebuilding the Index
+
+If `index.json` is missing or stale, rebuild from JSONL source files:
+
+1. Glob `accounts/<PROFILE>/feedback/*.jsonl`
+2. For each file, count records by outcome
+3. For each file, find most frequent `relatedError` → `topIssue`
+4. Write `index.json`
+
+## No Planning Gate
+
+This skill is read-only by default (dashboard, review, export). Only `promote` modifies files, and it has its own guardrails. No planning gate required.
+
+## Known Pitfalls
+<!-- feedback-promoted: managed section, updated by feedback loop -->
+
+_(No promoted learnings yet — this section will be populated as the feedback loop matures.)_
+
+<!-- end feedback-promoted -->