---
name: fluent-knowledge-init
description: "Interactive wizard to set up project knowledge. Asks plain-English questions, ingests existing docs, or captures progressive learnings — then writes structured knowledge files. Triggers on \"knowledge init\", \"set up knowledge\", \"project knowledge\", \"teach me about your project\", \"knowledge setup\", \"onboard knowledge\"."
user-invocable: true
read-only: false
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
argument-hint: "[--from <file>] [--topic <naming|rules|integrations|data-model|test-data|vertical>] [--profile <PROFILE>]"
cursor-tier: auto
---

# Fluent Knowledge Init

Interactive wizard that populates `accounts/<PROFILE>/knowledge/` with account-specific project knowledge. The client talks, the AI writes.

## Ownership Boundary

| Task | This Skill | Chain To |
|------|-----------|----------|
| Set up project knowledge from conversation | Yes | — |
| Ingest existing docs into knowledge files | Yes | — |
| Update existing knowledge files | Yes | — |
| Use knowledge during workflow building | No | `/fluent-workflow-builder` (reads knowledge in pre-flight) |
| Use knowledge during rule scaffolding | No | `/fluent-rule-scaffold` (reads knowledge in pre-flight) |
| Use knowledge during feature planning | No | `/fluent-feature-plan` (reads knowledge in pre-flight) |

## Modes

### Mode A: Full Wizard (default)

Walk through all topics in priority order. Ask conversational questions, write files as you go.

### Mode B: Single Topic (`--topic`)

Focus on one topic only. Useful for adding knowledge incrementally.

### Mode C: Document Ingestion (`--from <file>`)

Read an existing document (PDF, markdown, text), extract knowledge, confirm with user, write files.

### Mode D: Environment Introspection (`--profile <PROFILE>`)

Query the live Fluent environment via MCP to auto-populate data model, test data, and org structure.

---

## Phase 0: Setup

### Check for existing knowledge

```bash
ls accounts/<PROFILE>/knowledge/ 2>/dev/null
```

- If `accounts/<PROFILE>/knowledge/` exists → read it, show current status, ask what to update
- If not → fresh setup, will create directory structure

### Detect mode

- `--from <file>` → Mode C (Document Ingestion)
- `--topic <topic>` → Mode B (Single Topic)
- `--profile <PROFILE>` → Mode D (Environment Introspection) — can combine with A or B
- No flags → Mode A (Full Wizard)

### Create directory structure if needed

```bash
mkdir -p accounts/<PROFILE>/knowledge/client accounts/<PROFILE>/knowledge/templates
```

---

## Phase 1: Partner Conventions (Topic: `naming`)

**Ask these questions conversationally — do NOT present a form:**

1. "How do you name order references? Any prefix, date, store code?"
   - If blank/unsure: suggest a sensible default, let them confirm

2. "What about fulfilment refs? Do they reference the parent order?"

3. "Location ref pattern? Any region or type codes?"

4. "Custom rule class naming — any prefix or package convention?"

5. "Workflow subtype naming — what subtypes do you use? (HD, CC, SFS, etc.)"

6. "Settings key prefix? (e.g., `acme.webhookUrl`)"

**After gathering answers:**
- Show a summary: "Here's what I'll write to `accounts/<PROFILE>/knowledge/naming-conventions.md`:"
- List each convention with examples
- Wait for confirmation
- Write the file with proper frontmatter

---

## Phase 2: Partner Conventions (Topic: `coding-standards`)

**Ask conversationally:**

1. "Any Java coding standards? Logging framework, error handling approach, test coverage expectations?"
   - If blank: skip — not all projects have custom Java rules

2. "Workflow JSON conventions? How do you name categories, statuses, rulesets?"

3. "Manifest conventions? Fragment naming, query patterns?"

4. "Deployment process? How many environments? Promotion order? Any approval gates?"

**After gathering:**
- Summarize, confirm, write to `accounts/<PROFILE>/knowledge/coding-standards.md`

---

## Phase 3: Client Business Rules (Topic: `rules`)

**Ask conversationally:**

1. "What are the main order routing rules? How do you decide where to fulfil from?"
   - Probe: "Any special handling for express, bulky, fragile, or high-value items?"

2. "Any fulfilment constraints? Max splits, pickup windows, cutoff times?"

3. "How do you handle exceptions? Out of stock, payment decline, carrier rejection?"

4. "Any SLAs? Dispatch times, delivery windows, return processing times?"

**After gathering:**
- Summarize, confirm, write to `accounts/<PROFILE>/knowledge/client/business-rules.md`

---

## Phase 4: Client Integrations (Topic: `integrations`)

**Ask conversationally:**

1. "What external systems do you integrate with? (ERP, ecommerce platform, WMS, carrier, payment, etc.)"

2. For each system mentioned:
   - "Is it inbound (sends to Fluent), outbound (Fluent sends to it), or both?"
   - "How does it connect? Webhook, REST API, batch file, message queue?"
   - "What triggers the integration? Which entity/status change?"

3. "Any webhook URLs or settings already configured?"

**After gathering:**
- Summarize, confirm, write to `accounts/<PROFILE>/knowledge/client/integrations.md`
- 

---

## Phase 5: Client Data Model (Topic: `data-model`)

**If `--profile` is set, auto-populate from environment:**

```
# Query workflows to discover entity types and subtypes
workflow.transitions entityType=ORDER entitySubtype=HD
workflow.transitions entityType=FULFILMENT entitySubtype=HD_WH

# Query locations
graphql.query query="{ locations(first:10) { edges { node { ref type status } } } }"

# List installed rules for attribute patterns
plugin.list
```

**Otherwise ask conversationally:**

1. "What entity types and subtypes do you use? (ORDER::HD, FULFILMENT::SFS, etc.)"

2. "Any custom attributes on orders? Fulfilments? Locations?"

3. "What's your product catalogue ref? Inventory catalogue ref?"

4. "Any custom location types beyond STORE and WAREHOUSE?"

**After gathering:**
- Summarize, confirm, write to `accounts/<PROFILE>/knowledge/client/data-model.md`

---

## Phase 6: Test Data (Topic: `test-data`)

**If `--profile` is set, auto-populate:**

```
# Discover profile details
environment.discover include=retailer

# Get some locations
graphql.query query="{ locations(first:5, status:\"ACTIVE\") { edges { node { ref name type } } } }"

# Get product catalogue
graphql.query query="{ productCatalogues(first:3) { edges { node { ref name } } } }"
```

**Otherwise ask:**

1. "What test location refs should I use?"
2. "Any test product refs?"
3. "Test customer IDs?"
4. "Carrier/shipping test accounts?"

**After gathering:**
- Summarize, confirm, write to `accounts/<PROFILE>/knowledge/client/test-data.md`

---

## Phase 7: Vertical (Topic: `vertical`)

**Ask:**

1. "What industry is this project? (grocery / fashion / electronics / b2b / marketplace / other)"

**If a known vertical:**
- Read `knowledge/templates/` for available templates
- Tell user: "I'll use {vertical} patterns as a starting point for business rules and data model"
- Note active vertical in account knowledge

**If `other`:**
- Skip — client's specific rules in business-rules.md are sufficient

---

## Phase 8: Document Ingestion (Mode C only)

When `--from <file>` is provided:

1. Read the file (supports PDF, markdown, text)
2. Extract knowledge organized by topic (written to `accounts/<PROFILE>/knowledge/`):
   - Business rules / routing logic → `client/business-rules.md`
   - Naming patterns → `naming-conventions.md`
   - Integration descriptions → `client/integrations.md`
   - Data model / entity types → `client/data-model.md`
   - Test data / environment info → `client/test-data.md`
3. Present extracted knowledge organized by topic
4. Ask: "Here's what I extracted. Anything to add, change, or remove?"
5. Apply corrections
6. Write files

---

## Phase 9: Finalize

### Update index.md

Ensure `accounts/<PROFILE>/knowledge/` files are up to date:
- Mark populated files as "Active" (not "Template")
- Set active vertical
- Update last-updated dates

### Update CLAUDE.md reference

Check if CLAUDE.md has a `## Project Knowledge` section:
```bash
grep -n "## Project Knowledge" CLAUDE.md
```

If not, add it (after the last existing section):
```markdown
## Project Knowledge

See `accounts/<PROFILE>/knowledge/` for account-specific conventions and rules.

Always-loaded conventions (MUST follow):
- `accounts/<PROFILE>/knowledge/naming-conventions.md` — entity/attribute naming rules
- `accounts/<PROFILE>/knowledge/coding-standards.md` — Java and workflow conventions
```

### Summary

Show the user what was created:

```
Knowledge setup complete:
- accounts/<PROFILE>/knowledge/naming-conventions.md       ✓ (12 conventions)
- accounts/<PROFILE>/knowledge/coding-standards.md         ✓ (8 standards)
- accounts/<PROFILE>/knowledge/client/business-rules.md    ✓ (15 rules)
- accounts/<PROFILE>/knowledge/client/integrations.md      ✓ (3 systems)
- accounts/<PROFILE>/knowledge/client/data-model.md        ✓ (auto-populated from environment)
- accounts/<PROFILE>/knowledge/client/test-data.md         ✓ (auto-populated from environment)
- accounts/<PROFILE>/knowledge/index.md                    ✓ (updated)
- CLAUDE.md                                ✓ (reference added)

Every future session will use this knowledge automatically.
To update later: /fluent-knowledge-init --topic <topic>
```

---

## Progressive Capture Protocol

This section applies to ALL skills, not just this wizard. When any skill detects a user correction that represents reusable project knowledge:

### When to capture

- User corrects a naming pattern: "No, we always prefix with ACME_"
- User corrects a business rule: "Bulky items never go to stores"
- User provides integration detail: "SAP webhook goes to this endpoint"
- User corrects data model assumption: "We use HD_WH not just HD for warehouse fulfilment"

### How to capture

1. Identify which knowledge file the correction belongs to
2. Read the existing file
3. Add or update the relevant section
4. Show user: "I've updated `accounts/<PROFILE>/knowledge/client/business-rules.md` with this rule. Look right?"
5. If confirmed, write the update

### When NOT to capture

- Session-specific context (current task, temp state)
- Platform knowledge (how Fluent works generically)
- Unconfirmed assumptions
- Sensitive data (credentials, API keys, tokens)

---

## Knowledge File Format Reference

All knowledge files use this format:

```yaml
---
name: <kebab-case-name>
scope: partner | client | vertical | integration
description: "<one-line description>"
load: always | on-demand | skill-triggered
priority: high | medium | low
relevant-skills: [<skill-name>, ...]        # Which skills should auto-load this
relevant-entities: [<ENTITY_TYPE>, ...]      # Which entity types trigger loading
version: 1.0
last-updated: <YYYY-MM-DD>
author: "<who created/last edited>"
---

# Title

Content in markdown. Use:
- Bullet lists for rules and conventions
- Tables for structured data
- YAML/JSON code blocks for machine-parseable configs
- HTML comments <!-- --> for template placeholders
```

### Loading strategies

| Value | Meaning | Used for |
|-------|---------|----------|
| `always` | Referenced from CLAUDE.md, always in context | Naming conventions, coding standards |
| `on-demand` | Skills read when `relevant-skills` matches | Business rules, integrations, data model |
| `skill-triggered` | Specific skill checks for this file | Deploy checklists, test templates |

---

## Known Pitfalls
<!-- feedback-promoted: managed section, updated by feedback loop -->

- Always confirm extracted knowledge before writing — never silently write from document ingestion
- Keep individual files under 200 lines — split large topics into sub-files
- Don't duplicate platform knowledge — focus on THIS project's specifics
- Don't capture credentials, API keys, or tokens in knowledge files
- If MCP environment introspection fails, fall back to conversational questions
- When updating existing files, preserve user's manual edits — append or merge, don't overwrite

<!-- end feedback-promoted -->
