flyee 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Flyee
 
-> AI Agent Framework — 21 specialist agents, 65+ skills, 40+ workflows. All runtimes.
+> AI Agent Framework — 22 specialist agents, 81 skills, 44 workflows. All runtimes.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -46,7 +46,7 @@ npx flyee --all             # All detected runtimes
 | `game-developer` | Game development |
 | ... and 13 more | Various domains |
 
-### 🧩 65+ Modular Skills
+### 🧩 81 Modular Skills
 
 Skills are knowledge modules that enhance your agent's capabilities:
 
@@ -54,12 +54,14 @@ Skills are knowledge modules that enhance your agent's capabilities:
 - **Testing Patterns** — Unit, integration, E2E strategies
 - **Design System Enforcement** — Token-based UI consistency
 - **SEO Fundamentals** — Core Web Vitals, E-E-A-T
-- **State Machine** — Local project state with crash recovery
-- **Verification Gate** — Mechanical verification (not vibes)
-- **Cost Tracking** — LLM usage monitoring per operation
-- ... and 58 more
+- **Quality Gates** — 8-question structured quality gates
+- **Hallucination Guard** — Detects empty completions
+- **Stuck Detection** — Breaks infinite agent loops
+- **Knowledge Persistence** — Cross-session memory
+- **Skill Discovery** — Auto-detect relevant skills
+- ... and 70 more
 
-### 🔄 40+ Automated Workflows
+### 🔄 44 Automated Workflows
 
 ```bash
 /new-task          # Add features with tracking
@@ -78,8 +80,8 @@ Skills are knowledge modules that enhance your agent's capabilities:
 your-project/
 ├── .agent/              ← Installed by flyee (runtime-specific)
 │   ├── agents/          ← 21 specialist agents
-│   ├── skills/          ← 65+ modular skills  
-│   ├── workflows/       ← 40+ automated workflows
+│   ├── skills/          ← 81 modular skills  
+│   ├── workflows/       ← 44 automated workflows
 │   ├── scripts/         ← Automation scripts
 │   └── bridge/          ← Optional: Flyee SaaS sync
 ├── .flyee/              ← Runtime state (auto-created)

package/bin/install.js

@@ -268,6 +268,15 @@ async function installForRuntime(runtimeKey, projectDir, dryRun) {
     copyDirRecursive(bridgeSrc, bridgeDest, adapter, config, dryRun, stats);
   }
 
+  // Merge global user skills from ~/.flyee/skills/ (F-11)
+  const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+  const globalSkillsDir = join(homeDir, '.flyee', 'skills');
+  if (existsSync(globalSkillsDir)) {
+    const globalSkillsDest = join(targetDir, 'skills');
+    console.log(`   🌐 Merging global skills from ~/.flyee/skills/`);
+    copyDirRecursive(globalSkillsDir, globalSkillsDest, adapter, config, dryRun, stats);
+  }
+
   // Generate engine file (always use GEMINI.md as canonical source, adapter converts)
   const engineFileSrc = join(ENGINE_FILES_DIR, 'GEMINI.md');
   const engineFileDest = join(projectDir, config.engineFileTarget);

package/core/skills/cost-tracking/SKILL.md

@@ -192,6 +192,73 @@ Output:
 
 ---
 
+## 📈 COST PROJECTIONS (F-07)
+
+Estimate remaining sprint cost based on completed work.
+
+### Formula
+
+```
+avg_cost_per_task = total_spent / completed_tasks
+remaining_cost = avg_cost_per_task × remaining_tasks
+projected_total = total_spent + remaining_cost
+```
+
+### Weighted Projection
+
+Simple average can be misleading (planning is cheap, execution is expensive). Use weighted projection:
+
+```python
+# Weight by operation type
+weights = {
+    "plan": 0.15,      # Planning is ~15% of task cost
+    "execute": 0.60,   # Execution is ~60%
+    "verify": 0.10,    # Verification is ~10%
+    "debug": 0.15,     # Debug is ~15%
+}
+
+# Calculate cost profile from completed tasks
+cost_profile = calculate_profile(completed_tasks)
+
+# Project remaining based on profile
+remaining = sum(
+    cost_profile[op] * remaining_tasks * weights[op]
+    for op in weights
+)
+```
+
+### Projection Event
+
+```python
+bridge.emit_event("cost.projection", {
+    "sprint": "S09",
+    "completed_tasks": 12,
+    "remaining_tasks": 4,
+    "spent_usd": 14.20,
+    "projected_remaining_usd": 4.72,
+    "projected_total_usd": 18.92,
+    "budget_usd": 15.00,
+    "over_budget": True,
+    "confidence": "medium"
+})
+```
+
+### Report Output
+
+```
+📈 PROJECTION:
+  Completed: 12/16 tasks (75%)
+  Avg cost/task: $1.18
+  Remaining 4 tasks: ~$4.72
+  Projected total: $18.92 (⚠️ over budget by $3.92)
+  Confidence: medium
+  
+  Recommendation: Switch to cheaper model for remaining tasks
+                   OR reduce scope by 1 task to stay in budget
+```
+
+---
+
 ## ⚡ QUICK REFERENCE
 
 ```bash
@@ -204,3 +271,4 @@ tail -20 .flyee/cost-log.jsonl | python3 -m json.tool
 # Set budget (in CONTEXT.md)
 echo "Budget: $15.00" >> .flyee/sprints/S09/CONTEXT.md
 ```
+

package/core/skills/doctor/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: doctor
+description: Auto-diagnostic health check for the flyee framework. Validates .flyee/ directory integrity, checks skill loading, verifies bridge connectivity, detects orphaned state, and reports actionable issues. Run manually or triggered by session-resilience on crash recovery.
+---
+
+# Doctor (Health Check)
+
+> Auto-diagnose the flyee framework state. Find and fix issues.
+
+## Purpose
+
+Things break silently. Stale lock files, corrupted state, missing skills, broken bridge connections. Doctor finds these issues before they cause failures during execution.
+
+## When to Run
+
+| Trigger | Automatic? |
+|---------|-----------|
+| Session start | Optional (configurable) |
+| Crash recovery | Yes (always) |
+| User runs `/doctor` or asks "check health" | Manual |
+| Before `/deploy` | Yes (always) |
+| After `npx flyee` install | Yes (first run) |
+
+## Health Checks
+
+### 1. `.flyee/` Directory Integrity
+
+```markdown
+## Check: .flyee/ Integrity
+
+- [ ] `.flyee/` directory exists
+- [ ] `STATE.md` exists and is parseable
+- [ ] `DECISIONS.md` exists
+- [ ] `config.json` exists and is valid JSON
+- [ ] `tasks.json` exists and is valid JSON (if tasks were created)
+- [ ] `cost-log.jsonl` has no malformed lines
+- [ ] `events.jsonl` has no malformed lines
+- [ ] No stale lock files (`auto.lock` with dead PID)
+```
+
+### 2. Skills Loading
+
+```markdown
+## Check: Skills
+
+- [ ] `core/skills/` directory exists
+- [ ] All skills have valid `SKILL.md` with frontmatter (name, description)
+- [ ] No broken symlinks in skills directory
+- [ ] Skill count matches expected (77 for v0.2.0)
+```
+
+### 3. Agent Integrity
+
+```markdown
+## Check: Agents
+
+- [ ] `core/agents/` directory exists
+- [ ] All agents have valid frontmatter with `skills:` field
+- [ ] Skills referenced in frontmatter exist in `core/skills/`
+- [ ] No circular agent references
+```
+
+### 4. Bridge Connectivity
+
+```markdown
+## Check: Bridge
+
+- [ ] `bridge/local_tracker.py` exists and is executable
+- [ ] Python 3 is available
+- [ ] `flyee.json` status:
+  - Exists + valid → "Connected to Flyee SaaS"
+  - Exists + `opted_out: true` → "Opted out of SaaS"
+  - Not exists → "Not configured"
+- [ ] If connected: API health check (GET /health)
+```
+
+### 5. State Consistency
+
+```markdown
+## Check: State Consistency
+
+- [ ] STATE.md phase matches tasks.json status
+- [ ] No tasks in "in_progress" for > 24 hours (likely abandoned)
+- [ ] No orphaned sprint directories in `.flyee/sprints/`
+- [ ] DECISIONS.md entries have valid dates
+- [ ] cost-log.jsonl timestamps are sequential (no time travel)
+```
+
+### 6. Git Health (if git repo)
+
+```markdown
+## Check: Git
+
+- [ ] `.git/` exists
+- [ ] Current branch is clean or has tracked changes
+- [ ] `.flyee/` entries in `.gitignore` are correct
+- [ ] No merge conflicts in tracked files
+```
+
+## Output Format
+
+```
+🏥 Flyee Doctor — Health Report
+═══════════════════════════════
+
+✅ .flyee/ directory: OK (7/7 checks passed)
+✅ Skills: OK (77 skills loaded)
+✅ Agents: OK (22 agents, all skills resolved)
+⚠️ Bridge: WARNING — flyee.json not found (offline mode)
+✅ State: OK (consistent)
+✅ Git: OK (clean, on branch main)
+
+Summary: 5/6 passed, 1 warning
+No action required.
+```
+
+### With Issues:
+
+```
+🏥 Flyee Doctor — Health Report
+═══════════════════════════════
+
+✅ .flyee/ directory: OK
+❌ Skills: FAIL
+   → Missing SKILL.md in: core/skills/broken-skill/
+   → Fix: Remove directory or add SKILL.md
+⚠️ Bridge: WARNING
+   → Stale lock file: .flyee/auto.lock (PID 12345 is dead)
+   → Fix: rm .flyee/auto.lock
+❌ State: FAIL
+   → Task T-003 in "in_progress" for 48 hours
+   → Fix: Update status or mark abandoned
+
+Summary: 3/6 passed, 1 warning, 2 failures
+
+Run `flyee doctor --fix` to auto-fix recoverable issues.
+```
+
+## Auto-Fix
+
+When `--fix` is passed (or during crash recovery):
+
+| Issue | Auto-Fix Action |
+|-------|----------------|
+| Stale lock file | Delete lock file |
+| Malformed JSONL line | Move to `.flyee/corrupted/` |
+| Missing STATE.md | Regenerate from tasks.json |
+| Abandoned tasks (>24h in_progress) | Mark as "blocked" |
+| Missing config.json | Create with defaults |
+
+## Event Emission
+
+```python
+bridge.emit_event("health.check", {
+    "checks_total": 6,
+    "checks_passed": 5,
+    "checks_warned": 1,
+    "checks_failed": 0,
+    "issues": [
+        {"check": "bridge", "level": "warning", "message": "flyee.json not found"}
+    ],
+    "auto_fixed": []
+})
+```
+
+## Integration
+
+- **session-resilience**: Doctor runs on crash recovery
+- **verification-gate**: Doctor is part of pre-deploy verification
+- **state-machine**: Doctor validates STATE.md consistency
+- **Flyee SaaS**: Health panel consumes doctor events (S-05)

package/core/skills/hallucination-guard/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: hallucination-guard
+description: Detects and rejects task completions where the agent produced no real work. Catches fabricated summaries, empty diffs, and zero-tool-call completions. Prevents wasted budget on phantom tasks.
+---
+
+# Hallucination Guard
+
+> Rejects task completions where no real work was done.
+
+## Problem
+
+Agents can produce detailed, confident-sounding summaries without actually writing any code or making any changes. This wastes budget and creates false progress.
+
+Common hallucination patterns:
+1. **Zero tool calls** — Agent describes what it "did" but never used any tools
+2. **Read-only session** — Agent read files but never wrote/modified anything
+3. **Self-referential completion** — Agent says "I've completed the task" without evidence
+4. **Summary fabrication** — Detailed summary that describes non-existent changes
+
+## Detection Protocol
+
+### Before Marking Task Complete
+
+Run the following checks:
+
+```markdown
+## Hallucination Guard Checklist
+
+1. [ ] **Files modified?** — At least ONE file was created or modified during this task
+2. [ ] **Meaningful diff?** — The diff contains substantive changes (not just whitespace/comments)
+3. [ ] **Tool calls made?** — Agent used write/create/edit tools (not just read/search)
+4. [ ] **Artifacts exist?** — Files mentioned in the summary actually exist on disk
+5. [ ] **Verification ran?** — At least one verification command was executed
+
+❌ Any unchecked → REJECT completion. Task needs actual work.
+```
+
+### Check 1: File Modification Check
+
+```
+Scan the session for tool calls that WRITE:
+- write_to_file / create_file
+- replace_file_content / multi_replace_file_content
+- run_command (that modifies files: mv, cp, sed, etc.)
+
+If ZERO write operations → HALLUCINATION DETECTED
+```
+
+### Check 2: Meaningful Diff Check
+
+```
+After task "completion", verify:
+- git diff shows substantive changes
+- Changed files are relevant to the task (not random files)
+- Changes are not just adding/removing blank lines or comments
+
+If diff is empty or trivial → HALLUCINATION DETECTED
+```
+
+### Check 3: Summary Cross-Reference
+
+```
+Parse the task summary for claims:
+- "Created file X" → verify X exists
+- "Modified function Y" → verify Y was actually changed
+- "Added test for Z" → verify test file exists and contains Z
+- "Fixed bug in W" → verify W has a diff
+
+If claims don't match reality → HALLUCINATION DETECTED
+```
+
+## Response Protocol
+
+| Detection | Action |
+|-----------|--------|
+| Zero tool calls | REJECT. Log incident. Retry task with explicit instruction: "You must use tools to make changes." |
+| Read-only session | REJECT. Log incident. Retry with: "Reading is not implementing. Write the code." |
+| Summary fabrication | REJECT. Log incident. Show discrepancy to user. |
+| Trivial diff | WARN. Ask user: "Only minor changes were made. Is this task actually done?" |
+
+## Event Emission
+
+When hallucination is detected, emit event for Flyee SaaS:
+
+```json
+{
+  "event_type": "hallucination.detected",
+  "payload": {
+    "task_id": "T-001",
+    "pattern": "zero_tool_calls",
+    "summary_length": 450,
+    "tool_calls_write": 0,
+    "tool_calls_read": 12,
+    "action": "rejected"
+  }
+}
+```
+
+## Integration
+
+- **task-complete workflow**: Run hallucination guard BEFORE quality gates
+- **cost-tracking**: Log wasted cost when hallucination is detected
+- **KNOWLEDGE.md**: If pattern recurs, add to Lessons Learned
+- **Flyee SaaS**: Dashboard shows hallucination rate per project (S-03)
+
+## Anti-Patterns
+
+- ❌ Don't count research/investigation tasks as hallucinations — some tasks are legitimately read-only
+- ❌ Don't flag documentation-only tasks — writing docs IS real work
+- ❌ Don't block on first detection — retry once before escalating to user

package/core/skills/knowledge-persistence/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: knowledge-persistence
+description: Cross-session knowledge persistence. Global + per-project KNOWLEDGE.md that accumulates rules, patterns, and lessons learned across sessions. Prevents the agent from repeating mistakes or forgetting decisions.
+---
+
+# Knowledge Persistence
+
+> Memória persistente cross-sessão. Acumula rules, patterns e lições aprendidas.
+
+## Purpose
+
+Without knowledge persistence, every new session starts from zero. The agent re-discovers the same patterns, re-makes the same mistakes, and ignores previous decisions.
+
+KNOWLEDGE.md solves this by providing a structured, append-only file that accumulates context across sessions.
+
+## Files
+
+| File | Scope | Location |
+|------|-------|----------|
+| `~/.flyee/KNOWLEDGE.md` | **Global** — applies to ALL projects | User home |
+| `.flyee/KNOWLEDGE.md` | **Project** — applies to THIS project only | Project root |
+
+Both files are loaded. Project-level overrides global when there's a conflict.
+
+## Protocol
+
+### 1. Load (Session Start)
+
+At session start, the agent MUST:
+
+```
+1. Check ~/.flyee/KNOWLEDGE.md → load if exists
+2. Check .flyee/KNOWLEDGE.md → load if exists
+3. Merge: project rules take priority over global rules
+```
+
+### 2. Detect (During Work)
+
+Knowledge entries are created when the agent:
+
+- Discovers a **non-obvious pattern** in the codebase
+- Makes a **mistake and corrects it** (lesson learned)
+- The user provides a **rule or preference** that should persist
+- A **decision** has broad impact beyond the current task
+- A **workaround** is needed for a tool/library quirk
+
+### 3. Write (Append-Only)
+
+KNOWLEDGE.md is **append-only**. Never delete entries. Mark obsolete entries with `[OBSOLETE]`.
+
+### Format
+
+```markdown
+# KNOWLEDGE
+
+> Auto-maintained by flyee. Append-only.
+
+## Rules
+
+- Always use `pnpm` in this project, never `npm`
+- API responses must follow the `{ data, error, meta }` envelope
+- [OBSOLETE] Use v2 API endpoints → v3 is now the standard
+
+## Patterns
+
+- Database migrations use `alembic` with auto-generated revisions
+- Components follow atomic design: atoms/ → molecules/ → organisms/
+- Error handling uses Result<T, E> pattern, never throw
+
+## Lessons Learned
+
+- [2026-03-15] Prisma generates types in node_modules/.prisma — don't add to tsconfig paths
+- [2026-03-20] React Server Components can't use useEffect — caught twice, now documented
+- [2026-03-28] Bridge API returns 502 under load — implemented retry with exponential backoff
+
+## Workarounds
+
+- Tailwind v4 doesn't support `@apply` in CSS modules — use inline styles or cn() utility
+- SQLite WAL mode required for concurrent reads during auto-mode
+```
+
+### 4. Prompt Integration
+
+When constructing a prompt for a task, inject relevant KNOWLEDGE.md entries:
+
+```
+## Active Knowledge
+
+The following rules and patterns apply to this project:
+{filtered entries from KNOWLEDGE.md relevant to the current task domain}
+```
+
+**Filtering rules:**
+- If task is frontend → inject Rules + Patterns tagged with frontend/UI/CSS/React
+- If task is backend → inject Rules + Patterns tagged with API/database/server
+- Always inject Rules (they apply globally)
+- Always inject recent Lessons Learned (last 10)
+
+### 5. Maintenance
+
+| Trigger | Action |
+|---------|--------|
+| User says "remember that..." | Append to Rules |
+| Agent discovers non-obvious pattern | Append to Patterns |
+| Agent makes a mistake and fixes it | Append to Lessons Learned |
+| User corrects agent behavior | Append to Rules with `[USER]` tag |
+| Entry is outdated | Mark `[OBSOLETE]`, don't delete |
+| File exceeds 200 entries | Summarize old entries, archive to `KNOWLEDGE-ARCHIVE.md` |
+
+## Anti-Patterns
+
+- ❌ Don't store task-specific details (that's for DECISIONS.md)
+- ❌ Don't store temporary workarounds without a date
+- ❌ Don't duplicate what's already in ARCHITECTURE.md or PROJECT.md
+- ❌ Don't store code snippets — reference files instead
+
+## Integration Points
+
+- **Session start**: Load and inject into context
+- **Task completion**: Check if new knowledge was discovered
+- **Error recovery**: Auto-generate Lessons Learned entry
+- **User correction**: Auto-append to Rules
+- **Bridge sync**: When connected to Flyee SaaS, knowledge syncs to Knowledge Hub (S-07)

package/core/skills/quality-gates/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: quality-gates
+description: Structured quality gates for planning and completion phases. 8-question evaluation protocol that ensures tasks meet minimum quality bar before being marked complete. Prevents premature completion and catches common oversights.
+---
+
+# Quality Gates
+
+> Structured quality gates with 8 mechanically verifiable questions.
+
+## Purpose
+
+Tasks often get marked "complete" when they're merely "code was written." Quality gates enforce a minimum bar by asking 8 specific questions that catch common oversights.
+
+## When to Apply
+
+| Phase | Gate | Trigger |
+|-------|------|---------|
+| Planning | **Planning Gate** | Before starting implementation |
+| Task completion | **Completion Gate** | Before marking task done |
+| Sprint completion | **Sprint Gate** | Before marking sprint/milestone done |
+
+## The 8 Questions
+
+### Planning Gate (Before Implementation)
+
+```markdown
+## Planning Quality Gate
+
+1. [ ] **Scope bounded?** — Can this task complete in ONE context window?
+2. [ ] **Must-haves defined?** — Are there mechanically verifiable outcomes (not vibes)?
+3. [ ] **Dependencies clear?** — Do I know what files/modules this touches?
+4. [ ] **Risk identified?** — What could go wrong? Is there a fallback?
+5. [ ] **Knowledge checked?** — Did I check KNOWLEDGE.md for relevant patterns/lessons?
+6. [ ] **Existing code reviewed?** — Did I READ the code I'm about to modify?
+7. [ ] **Tests planned?** — Do I know HOW I'll verify this works?
+8. [ ] **No gold-plating?** — Am I building ONLY what's needed?
+
+❌ Any unchecked → STOP. Address before proceeding.
+```
+
+### Completion Gate (Before Marking Task Done)
+
+```markdown
+## Completion Quality Gate
+
+1. [ ] **Truths verified?** — All must-haves are mechanically confirmed (not "I think it works")?
+2. [ ] **Artifacts exist?** — All files that should exist DO exist with real implementation?
+3. [ ] **Key links wired?** — Imports, routes, and integrations are connected?
+4. [ ] **No mock data?** — Production code uses real data sources, not hardcoded values?
+5. [ ] **Tests pass?** — All configured verification commands succeed?
+6. [ ] **No regressions?** — Existing tests still pass?
+7. [ ] **Knowledge captured?** — Did I learn something that should go in KNOWLEDGE.md?
+8. [ ] **Clean diff?** — Only intended changes in the diff? No debug logs, console.logs, TODOs?
+
+❌ Any unchecked → STOP. Fix before completing.
+```
+
+### Sprint Gate (Before Marking Sprint/Milestone Done)
+
+```markdown
+## Sprint Quality Gate
+
+1. [ ] **All tasks complete?** — Every task passed its Completion Gate?
+2. [ ] **Success criteria met?** — Roadmap success criteria are satisfied?
+3. [ ] **Integration tested?** — Components work TOGETHER, not just individually?
+4. [ ] **No orphaned code?** — No dead code, unused imports, or abandoned experiments?
+5. [ ] **Documentation updated?** — README, API docs, ARCHITECTURE.md reflect changes?
+6. [ ] **Cost within budget?** — Sprint cost didn't exceed ceiling?
+7. [ ] **Knowledge persisted?** — KNOWLEDGE.md updated with sprint lessons?
+8. [ ] **Stakeholder verifiable?** — A human can verify the sprint outcomes without reading code?
+
+❌ Any unchecked → STOP. Address before sealing sprint.
+```
+
+## Evaluation Protocol
+
+Gates are evaluated **in parallel** when possible:
+
+```
+Questions 1-4 → Can be checked mechanically (automated)
+Questions 5-6 → Require running commands (semi-automated)
+Questions 7-8 → Require judgment (agent evaluates)
+```
+
+### Scoring
+
+| Score | Result | Action |
+|-------|--------|--------|
+| 8/8 | ✅ PASS | Proceed |
+| 6-7/8 | 🟡 WARN | Proceed with documented exceptions |
+| ≤5/8 | ❌ FAIL | STOP. Address failures before proceeding. |
+
+### Exception Protocol
+
+If a gate question genuinely doesn't apply:
+
+```markdown
+- Q7 (Knowledge captured): N/A — routine change, no new patterns discovered
+```
+
+Mark N/A with justification. N/A counts as passed. But **never N/A more than 2 questions** — if 3+ don't apply, the gate itself may be wrong for this context.
+
+## Integration
+
+- **task-complete workflow**: Insert Completion Gate before `--update-task completed`
+- **verification-gate skill**: Quality gates complement, not replace, verification
+- **cost-tracking skill**: Q6 of Sprint Gate uses cost data
+- **knowledge-persistence skill**: Q7 feeds into KNOWLEDGE.md
+- **Flyee SaaS**: Gate results are emitted as events for dashboard visualization