wogiflow 1.0.21 → 1.0.22

package/.claude/rules/code-style/naming-conventions.md

@@ -0,0 +1,55 @@
+---
+alwaysApply: true
+description: "Naming conventions for files and code variants"
+---
+
+# Naming Conventions
+
+## File Names
+
+Use **kebab-case** for all file names in this project.
+
+Examples:
+- `flow-health.js` (correct)
+- `flowHealth.js` (incorrect)
+- `flow_health.js` (incorrect)
+
+## Variant Names
+
+Use consistent variant names for components:
+
+| Category | Values |
+|----------|--------|
+| Size | `sm`, `md`, `lg`, `xl` |
+| Intent | `primary`, `secondary`, `danger`, `success`, `warning` |
+| State | `default`, `hover`, `active`, `disabled` |
+
+Examples:
+```jsx
+<Button size="sm" intent="primary" />
+<Badge variant="warning" />
+```
+
+## Catch Block Variables
+
+Use `err` for all catch blocks in this codebase.
+
+**Avoid**: `e`, `error`, `ex`, `exception` - these cause confusion with loop variables.
+
+```javascript
+// Good
+try {
+  doSomething();
+} catch (err) {
+  console.error(err.message);
+}
+
+// Bad - 'e' conflicts with common iterator variables
+try {
+  items.map(e => e.value);  // 'e' used as iterator
+} catch (e) {
+  console.error(e.message);  // Easy to confuse with iterator 'e'
+}
+```
+
+**Reason**: Standardizing on `err` prevents mix-ups when `.map(e => ...)` is used nearby.

package/.claude/rules/security/security-patterns.md

@@ -0,0 +1,116 @@
+---
+alwaysApply: true
+description: "Security patterns for file operations, JSON parsing, and path handling"
+---
+
+# Security Patterns
+
+Critical security patterns for this project.
+
+## 1. File Read Safety
+
+Always wrap `fs.readFileSync()` in try-catch, even after `fileExists()` check.
+
+**Reason**: Race conditions, permission changes, symlink issues can still cause failures.
+
+```javascript
+// Good
+try {
+  const content = fs.readFileSync(path, 'utf-8');
+} catch (err) {
+  // Handle gracefully
+}
+
+// Bad - can still throw even if file existed
+if (fs.existsSync(path)) {
+  const content = fs.readFileSync(path, 'utf-8');
+}
+```
+
+## 2. JSON Parsing Safety
+
+Use `safeJsonParse()` from flow-utils.js instead of raw `JSON.parse()`.
+
+- Check for `__proto__`, `constructor`, `prototype` injection
+- Validate parsed structure has expected fields before use
+- Located in: `scripts/flow-utils.js`
+
+```javascript
+// Good
+const config = safeJsonParse(filePath, {});
+
+// Bad - vulnerable to prototype pollution
+const config = JSON.parse(fs.readFileSync(filePath));
+```
+
+## 3. Template Substitution Safety
+
+When implementing template substitution:
+- Block access to `__proto__`, `constructor`, `prototype` keys
+- Use `Object.prototype.hasOwnProperty.call()` for property access
+- Example: See `applyTemplate()` in flow-prompt-composer.js
+
+## 4. Path Safety
+
+- Validate patterns before `path.join()` with user/config data
+- Use `isPathWithinProject()` for defense-in-depth
+- Glob-to-regex: Use `[^/]*` not `.*` to prevent path separator matching
+
+```javascript
+// Good
+if (!isPathWithinProject(targetPath)) {
+  throw new Error('Path outside project');
+}
+
+// Bad - allows path traversal
+const fullPath = path.join(baseDir, userInput);
+```
+
+## 5. Module Dependencies
+
+- Check for circular dependencies when refactoring shared functions
+- Node.js handles circular deps but can cause undefined exports during load
+
+## 6. Claude Code Permission Patterns (2.1.7+)
+
+When configuring permission rules in Claude Code, avoid overly permissive wildcards.
+
+**Vulnerability fixed in 2.1.7**: Wildcard permission rules could match compound commands containing shell operators (`;`, `&&`, `||`, `|`).
+
+```javascript
+// DANGEROUS - could match "npm test && rm -rf /"
+"allow": "npm *"
+
+// SAFER - be specific about allowed commands
+"allow": "npm test"
+"allow": "npm run build"
+"allow": "npm install"
+
+// BEST - use semantic prompts instead of wildcards
+// In ExitPlanMode allowedPrompts:
+{ "tool": "Bash", "prompt": "run tests" }
+{ "tool": "Bash", "prompt": "install dependencies" }
+```
+
+**Best practices:**
+- Avoid `*` wildcards in permission rules
+- Use specific command patterns
+- Prefer semantic permission prompts over literal command matching
+- Never allow broad patterns like `rm *` or `git *`
+- Review permission rules after Claude Code updates
+
+## 7. Windows Path Safety
+
+On Windows, be aware of path-related issues:
+
+- Temp directory paths may contain characters like `\t` or `\n` that could be misinterpreted as escape sequences
+- Use raw strings or proper escaping when constructing paths
+- Cloud sync tools (OneDrive, Dropbox) and antivirus may touch file timestamps without changing content
+
+```javascript
+// Good - use path.join() which handles platform differences
+const tempPath = path.join(os.tmpdir(), 'myfile.txt');
+
+// Bad - manual concatenation can break on Windows
+const tempPath = os.tmpdir() + '/myfile.txt';
+```

package/.claude/skills/README.md

@@ -0,0 +1,131 @@
+# WogiFlow Skills
+
+Skills are modular add-ons that extend WogiFlow with specialized commands, templates, and rules for specific tech stacks.
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `nestjs` | NestJS module builder with TypeORM |
+| `react` | React component patterns (coming soon) |
+| `python` | Python/FastAPI patterns (coming soon) |
+
+## Installing Skills
+
+After installing WogiFlow:
+
+```
+/wogi-skills add nestjs
+```
+
+Or manually:
+1. Copy skill folder to `.claude/skills/`
+2. Add skill name to `config.json` → `skills.installed`
+
+## Using Skills
+
+Once installed, skill commands are available:
+
+```
+# NestJS skill
+/nestjs-scaffold users        # Create complete module
+/nestjs-entity User           # Create entity
+/nestjs-db migrate            # Run migrations
+```
+
+## Skill Structure
+
+Each skill follows this structure:
+
+```
+.claude/skills/[name]/
+├── skill.md              # Description, when to use, commands list
+├── rules/                # Coding conventions (auto-loaded)
+│   ├── conventions.md
+│   └── [topic].md
+├── commands/             # Slash commands
+│   ├── scaffold.md       # Becomes /[name]-scaffold
+│   └── [action].md
+└── templates/            # Code templates
+    ├── entity.template.ts
+    └── [type].template.ts
+```
+
+## Creating Custom Skills
+
+### 1. Create Skill Directory
+
+```bash
+mkdir -p .claude/skills/my-skill/{rules,commands,templates}
+```
+
+### 2. Create skill.md
+
+```markdown
+# My Skill
+
+Description of what this skill does.
+
+## When to Use
+
+- Creating [type] components
+- Working with [technology]
+
+## Commands Added
+
+| Command | Description |
+|---------|-------------|
+| `/my-skill-action` | Does something |
+```
+
+### 3. Add Commands
+
+Create `.claude/skills/my-skill/commands/action.md`:
+
+```markdown
+Do the action for my skill.
+
+Usage: `/my-skill-action [args]`
+
+## Steps
+
+1. Read templates from skill folder
+2. Generate files
+3. Report results
+```
+
+### 4. Add Rules
+
+Create `.claude/skills/my-skill/rules/conventions.md`:
+
+```markdown
+# My Skill Conventions
+
+## Pattern 1
+
+Always do X when Y.
+
+## Pattern 2
+
+Never do A because B.
+```
+
+### 5. Add Templates
+
+Create template files that commands will use.
+
+### 6. Register Skill
+
+Add to `config.json`:
+```json
+"skills": {
+  "installed": ["my-skill"]
+}
+```
+
+## Sharing Skills
+
+Skills can be:
+- Included in project repo
+- Shared via `/wogi-export` profile
+- Published to skill repository (coming soon)

package/.claude/skills/_template/knowledge/anti-patterns.md

@@ -0,0 +1,49 @@
+# Anti-Patterns
+
+Things that DON'T work. Learn from past mistakes.
+This file is automatically updated when errors occur.
+
+---
+
+## Code Anti-Patterns
+
+_No anti-patterns recorded yet._
+
+<!--
+Example anti-pattern entry:
+
+### Anti-Pattern: Descriptive Name
+
+**What happened**: Description of the mistake
+**Why it's wrong**: Explanation
+**What to do instead**: Correct approach
+**First encountered**: YYYY-MM-DD
+**Occurrence count**: N times
+
+```typescript
+// BAD - Don't do this
+badCode();
+
+// GOOD - Do this instead
+goodCode();
+```
+-->
+
+## Workflow Anti-Patterns
+
+_No workflow anti-patterns recorded yet._
+
+## Common Errors
+
+_No common errors recorded yet._
+
+<!--
+Example:
+
+### Error: TypeScript error TS2345
+
+**When it occurs**: Passing wrong type to function X
+**Root cause**: Usually because...
+**Fix**: Cast the type or use...
+**Prevention**: Always check types before...
+-->

package/.claude/skills/_template/knowledge/learnings.md

@@ -0,0 +1,60 @@
+# Learnings Log
+
+This file is automatically updated when corrections or insights occur.
+Each entry captures context, what happened, and what to remember.
+
+---
+
+## What to Capture Here
+
+Capture learnings when:
+- **User corrects you** - They say "no, do X instead" or "that's wrong"
+- **Something breaks** - Build fails, tests fail, runtime error
+- **You discover a project convention** - "Ah, this project uses X pattern"
+- **A workaround is needed** - Library bug, platform limitation, edge case
+- **Something works unexpectedly well** - Shortcut that's now a pattern
+
+## Good Learning vs Noise
+
+**Worth capturing:**
+- "Module imports must use `.js` extension in this ESM project"
+- "The auth middleware expects `req.user.id`, not `req.userId`"
+- "Tests fail if database isn't seeded first"
+
+**Not worth capturing:**
+- "Fixed typo in variable name" (too trivial)
+- "Added console.log for debugging" (temporary)
+- "Used different CSS color" (preference, not pattern)
+
+## When to Promote to patterns.md or anti-patterns.md
+
+A learning should be promoted when:
+1. **Same issue occurs 3+ times** - It's a pattern, not a one-off
+2. **It affects multiple files** - Project-wide concern
+3. **It cost significant time** - Worth preventing in future
+
+To promote:
+1. Move the core insight to `patterns.md` (if positive) or `anti-patterns.md` (if negative)
+2. Add code examples if relevant
+3. Keep the original learning entry as history
+
+---
+
+## Entry Format
+
+```markdown
+### YYYY-MM-DD - Brief title
+
+**Context**: What was being done
+**Trigger**: commit | task-complete | correction | manual
+**Issue**: What went wrong (or worked well)
+**Learning**: Pattern to remember for future
+**Files**: Affected files (if any)
+**Related**: Link to request-log entry (if any)
+```
+
+---
+
+## Recent Learnings
+
+_No learnings recorded yet. This file will be updated automatically as you work._

package/.claude/skills/_template/knowledge/patterns.md

@@ -0,0 +1,45 @@
+# Successful Patterns
+
+Patterns that have proven to work well in this project.
+These are extracted from successful task completions.
+
+---
+
+## Code Patterns
+
+_No patterns recorded yet._
+
+<!--
+Example pattern entry:
+
+### Pattern: Descriptive Name
+
+**Context**: When this pattern applies
+**Example**:
+```typescript
+// Code example here
+```
+**Why it works**: Explanation
+**First seen**: YYYY-MM-DD
+**Usage count**: N times
+-->
+
+## Workflow Patterns
+
+_No workflow patterns recorded yet._
+
+<!--
+Example:
+
+### Pattern: Always run X before Y
+
+**Context**: When doing Z
+**Steps**:
+1. First do X
+2. Then do Y
+**Why**: Prevents issues with...
+-->
+
+## Testing Patterns
+
+_No testing patterns recorded yet._

package/.claude/skills/_template/skill.md

@@ -0,0 +1,99 @@
+---
+name: _template
+version: 1.0.0
+description: Template for creating new skills - DO NOT LOAD
+scope: project
+user-invocable: false
+context: inline
+agent: developer
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Edit
+  - Write
+lastUpdated: {{DATE}}
+learningCount: 0
+successRate: 0
+template: true
+loadable: false
+---
+
+<!--
+  ⚠️  THIS IS A TEMPLATE - DO NOT LOAD THIS SKILL
+
+  To create a new skill, copy this directory and replace:
+  - {{SKILL_NAME}} with your skill name
+  - {{SHORT_DESCRIPTION}} with a brief description
+  - {{USE_CASE_*}} with actual use cases
+  - {{FILE_PATTERN_*}} with file globs
+  - {{DATE}} with current date
+
+  ## Frontmatter Fields (Claude Code 2.1.x aligned)
+
+  Required:
+  - name: Skill identifier (kebab-case)
+  - description: Short description shown in slash command menu
+  - scope: project | user (where skill applies)
+
+  Claude Code 2.1.x fields:
+  - user-invocable: true | false (controls /slash command visibility)
+  - context: inline | fork (fork = isolated execution context)
+  - agent: orchestrator | developer | reviewer | tester (persona mapping)
+  - allowed-tools: YAML list of tools the skill can use
+    Example: [Read, Glob, Grep, Edit, Write, Bash(npm *), Bash(git *)]
+
+  Optional:
+  - lastUpdated: ISO date string
+  - learningCount: Number of learnings captured
+  - successRate: Historical success rate (0-1)
+  - loadable: true | false (whether skill can be loaded)
+  - template: true (only for _template skill)
+-->
+
+# {{SKILL_NAME}} Skill
+
+## When to Use
+
+- {{USE_CASE_1}}
+- {{USE_CASE_2}}
+
+## Quick Reference
+
+### Key Patterns
+- Pattern 1: Description
+- Pattern 2: Description
+
+### Common Mistakes to Avoid
+- See `knowledge/anti-patterns.md` for details
+
+## Progressive Content
+
+Load these files when relevant:
+
+| File | When to Load |
+|------|--------------|
+| `knowledge/learnings.md` | Starting a task with this skill |
+| `knowledge/patterns.md` | Looking for examples |
+| `knowledge/anti-patterns.md` | Reviewing code or fixing issues |
+| `rules/conventions.md` | Writing new code |
+
+## File Patterns
+
+This skill applies to files matching:
+- `{{FILE_PATTERN_1}}`
+- `{{FILE_PATTERN_2}}`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/{{SKILL_NAME}}-{{ACTION}}` | Description |
+
+## Integration
+
+### Dependencies
+- None
+
+### Related Skills
+- None