flyee 0.1.0 → 0.2.0

package/core/skills/roadmap-reassessment/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: roadmap-reassessment
+description: Automatically reassess the project roadmap after each phase/sprint completes. Checks if learned information changes the plan, reorders priorities, and adjusts scope. Prevents executing an outdated plan when reality has shifted.
+---
+
+# Roadmap Reassessment
+
+> Reavaliar o plano após cada phase completada.
+
+## Problem
+
+Plans are made with incomplete information. As work progresses, the agent learns:
+- A dependency is harder than expected
+- A feature is simpler than planned
+- A new requirement emerged
+- A technical constraint was discovered
+- An approach was abandoned in favor of a better one
+
+Without reassessment, the agent blindly follows the original plan even when it no longer makes sense.
+
+## When to Trigger
+
+| Trigger | Reassessment Type |
+|---------|-------------------|
+| Phase/Sprint completed | **Full reassessment** |
+| Major blocker found | **Emergency reassessment** |
+| User changes requirements | **Scope reassessment** |
+| Budget milestone (50%, 75%) | **Budget reassessment** |
+
+## Reassessment Protocol
+
+### Step 1: Gather Evidence
+
+```markdown
+What changed since the plan was made?
+
+1. **Completed work**: What was done? What was learned?
+2. **Discovered complexity**: What was harder/easier than expected?
+3. **New dependencies**: What new dependencies were discovered?
+4. **Abandoned approaches**: What was tried and didn't work?
+5. **Cost reality**: How much budget was used vs planned?
+```
+
+### Step 2: Evaluate Remaining Plan
+
+For each remaining phase/task, ask:
+
+```markdown
+| Phase | Still Valid? | Priority Changed? | Effort Changed? | Action |
+|-------|-------------|-------------------|-----------------|--------|
+| Phase N+1 | Yes/No | ↑↓→ | ↑↓→ | Keep/Reorder/Split/Remove |
+| Phase N+2 | Yes/No | ↑↓→ | ↑↓→ | Keep/Reorder/Split/Remove |
+```
+
+### Step 3: Decide
+
+| Decision | When |
+|----------|------|
+| **Keep** | Plan is still valid. No changes. |
+| **Reorder** | Priorities shifted. Move phases up/down. |
+| **Split** | A phase is too large. Break it into smaller phases. |
+| **Merge** | Two phases are related and should be combined. |
+| **Remove** | Phase is no longer needed. |
+| **Add** | New phase needed based on discoveries. |
+| **Pause** | Need user input before continuing. |
+
+### Step 4: Update Artifacts
+
+If the plan changed:
+
+1. Update `implementation_plan.md` or equivalent planning doc
+2. Update `.flyee/STATE.md` with new phase order
+3. Add entry to `.flyee/DECISIONS.md`:
+   ```markdown
+   ## [DATE] Roadmap Reassessment after Phase N
+   
+   **Trigger:** Phase N completed
+   **Changes:**
+   - Phase N+2 moved before N+1 (dependency discovered)
+   - Phase N+3 removed (handled by Phase N)
+   - New Phase N+4 added (edge case found)
+   **Rationale:** [explanation]
+   ```
+4. Emit event for Flyee SaaS
+
+### Step 5: Notify
+
+```markdown
+📋 **Roadmap Reassessment Complete**
+
+Phase {N} finished. Here's what changed:
+
+| Change | Detail |
+|--------|--------|
+| ✅ Completed | Phase {N}: {description} |
+| 🔄 Reordered | Phase {X} moved up (blocking dependency) |
+| ➕ Added | Phase {Y}: {new discovery} |
+| 🗑️ Removed | Phase {Z}: {no longer needed} |
+
+Budget: ${used} / ${ceiling} ({percentage}%)
+Remaining phases: {count}
+Estimated remaining cost: ${projection}
+
+Continue? (yes / review changes / pause)
+```
+
+## Budget Reassessment
+
+At cost milestones (50%, 75%, 90%):
+
+```markdown
+💰 **Budget Reassessment — {percentage}% Used**
+
+Spent: ${used} on {completed_phases} phases
+Remaining: ${remaining} for {remaining_phases} phases
+Avg cost per phase: ${avg}
+Projected total: ${projection}
+
+| Action | Description |
+|--------|-------------|
+| Continue | Budget is sufficient |
+| Trim scope | Remove low-priority phases to stay in budget |
+| Request increase | Ask user for more budget |
+| Switch models | Use cheaper models for remaining work |
+```
+
+## Integration
+
+- **state-machine**: Reads phases from STATE.md
+- **cost-tracking**: Provides budget data for budget reassessment
+- **quality-gates**: Sprint Gate triggers reassessment
+- **knowledge-persistence**: Reassessment decisions go to KNOWLEDGE.md
+- **context-budget**: Validates new phases fit in context windows
+- **Flyee SaaS**: Reassessment events update project timeline (S-02, S-03)

package/core/skills/skill-discovery/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: skill-discovery
+description: Automatic discovery and suggestion of relevant skills based on the current task context. Modes - auto (load silently), suggest (recommend to user), off (manual only). Replaces static frontmatter-only loading with dynamic detection.
+---
+
+# Skill Discovery
+
+> Auto-detect and load relevant skills based on task context.
+
+## Problem
+
+Current approach: skills are loaded via agent frontmatter (`skills: [a, b, c]`). This is static — if the agent lists 10 skills, ALL 10 are loaded regardless of whether they're relevant to the current task.
+
+GSD-2 approach: skills are discovered dynamically based on the task context. A "Fix CSS bug" task loads frontend skills. A "Database migration" task loads backend skills.
+
+## Modes
+
+Configure in `.flyee/config.json`:
+
+```json
+{
+  "skill_discovery": "suggest"
+}
+```
+
+| Mode | Behavior |
+|------|----------|
+| `auto` | Discover and load relevant skills silently |
+| `suggest` | Discover skills, show to user, ask before loading |
+| `off` | Only load skills explicitly listed in agent frontmatter |
+
+## Discovery Algorithm
+
+### Step 1: Context Analysis
+
+Analyze the user's request for signals:
+
+```
+Input: "Fix the login form validation on mobile"
+
+Signals detected:
+- "fix" → debugging domain
+- "login form" → frontend/UI domain
+- "validation" → form patterns
+- "mobile" → mobile-responsive/mobile-design
+```
+
+### Step 2: Skill Matching
+
+Match signals to skill domains:
+
+```
+Signal → Skill Mapping:
+
+frontend/UI/CSS/React     → frontend-design, nextjs-react-expert, tailwind-patterns
+backend/API/database      → api-patterns, database-design, nodejs-best-practices
+mobile/iOS/Android        → mobile-design
+security/auth/OWASP       → vulnerability-scanner, red-team-tactics
+testing/test/jest         → testing-patterns, tdd-workflow, webapp-testing
+git/branch/commit         → git-workflow
+debug/fix/error           → systematic-debugging
+design/UI/component       → design-system-enforcement, atomic-design
+deploy/production/CI      → deployment-procedures
+performance/slow/optimize → performance-profiling, nextjs-react-expert
+SEO/search/meta           → seo-fundamentals, geo-fundamentals
+```
+
+### Step 3: File Context
+
+Also check which files are being modified:
+
+```
+*.tsx, *.jsx, *.css     → frontend-design
+*.py                    → python-patterns
+*.ts (backend)          → nodejs-best-practices
+package.json            → project-setup
+Dockerfile              → server-management
+*.test.*, *.spec.*      → testing-patterns
+```
+
+### Step 4: Confidence Scoring
+
+Each potential skill gets a confidence score:
+
+| Factor | Weight |
+|--------|--------|
+| Direct keyword match | 0.4 |
+| File extension match | 0.3 |
+| Agent frontmatter includes it | 0.2 |
+| Recently used (last 3 sessions) | 0.1 |
+
+**Load threshold:** score >= 0.5
+
+### Step 5: Present/Load
+
+**Mode: auto**
+```
+🧩 Auto-loaded skills: frontend-design, testing-patterns
+```
+
+**Mode: suggest**
+```markdown
+🧩 **Suggested skills for this task:**
+
+| Skill | Confidence | Reason |
+|-------|-----------|--------|
+| frontend-design | 0.85 | Keywords: "form", "mobile"; Files: .tsx |
+| testing-patterns | 0.65 | Keyword: "validation" |
+| mobile-design | 0.55 | Keyword: "mobile" |
+
+Load these skills? (yes / select / no)
+```
+
+## Always-Load Skills
+
+Some skills should ALWAYS be loaded regardless of discovery:
+
+```json
+{
+  "always_load_skills": [
+    "clean-code",
+    "knowledge-persistence",
+    "quality-gates"
+  ]
+}
+```
+
+## Staleness (Future — F-18)
+
+Skills not used for N sessions get deprioritized:
+
+```json
+{
+  "skill_staleness_sessions": 20
+}
+```
+
+Usage tracking in `.flyee/skill-usage.json`:
+```json
+{
+  "frontend-design": { "last_used": "2026-03-31", "count": 15 },
+  "game-development": { "last_used": "2026-01-15", "count": 2 }
+}
+```
+
+## Integration
+
+- **intelligent-routing**: Skill discovery runs AFTER agent routing
+- **context-budget**: Discovered skills count against context budget
+- **knowledge-persistence**: Skill effectiveness feeds into KNOWLEDGE.md
+- **cost-tracking**: Track if skill loading improved task outcomes
+- **Flyee SaaS**: Skill usage analytics in dashboard

package/core/skills/sprint-validation/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: sprint-validation
+description: Gate de conclusão de sprint/milestone. Compara success criteria do roadmap contra resultados reais antes de selar o sprint. Diferente de quality-gates (que é por task) — este é o gate FINAL do sprint inteiro.
+---
+
+# Sprint Validation Gate
+
+> O gate final antes de marcar um sprint/milestone como concluído.
+
+## Purpose
+
+Individual tasks can pass their quality gates while the sprint as a whole fails. Examples:
+- Each task works in isolation, but they don't work together
+- All code is written, but the feature doesn't meet the original requirements
+- Tests pass, but the user story isn't fulfilled
+
+Sprint validation catches these by comparing **planned outcomes** against **actual results**.
+
+## When to Trigger
+
+- Before marking any sprint/milestone as "completed"
+- After ALL tasks in the sprint have their own Completion Gates passed
+- Before the final git commit/merge for the sprint
+
+## Validation Protocol
+
+### Step 1: Gather Success Criteria
+
+Read the sprint planning document for defined success criteria:
+
+```markdown
+## Sprint S09 — Blog & CMS
+
+### Success Criteria (from planning)
+1. Blog posts can be created, edited, and published
+2. CMS admin panel with CRUD operations
+3. SEO metadata auto-generated for each post
+4. RSS feed available at /feed.xml
+5. Performance: LCP < 2.5s on blog pages
+```
+
+### Step 2: Verify Each Criterion
+
+For each success criterion, provide **evidence**:
+
+```markdown
+## Sprint Validation — S09
+
+| # | Criterion | Status | Evidence |
+|---|-----------|--------|----------|
+| 1 | Blog CRUD | ✅ | Routes exist: POST/GET/PUT/DELETE /api/posts |
+| 2 | CMS admin | ✅ | Page exists: /admin/posts with DataTable |
+| 3 | SEO metadata | ✅ | generateMetadata() in app/blog/[slug]/page.tsx |
+| 4 | RSS feed | ❌ | /feed.xml returns 404 — NOT IMPLEMENTED |
+| 5 | LCP < 2.5s | ⚠️ | Not measurable without deployment |
+```
+
+### Step 3: Integration Check
+
+Beyond individual criteria, verify components work together:
+
+```markdown
+## Integration Verification
+
+- [ ] E2E flow works: Create post → Edit → Publish → View on blog → Appears in RSS
+- [ ] All routes registered in router/navigation
+- [ ] Database migrations applied without conflict
+- [ ] No import cycles between modules
+- [ ] Shared types/interfaces consistent across components
+```
+
+### Step 4: Decision
+
+| Result | Action |
+|--------|--------|
+| All criteria ✅ | Sprint PASS → mark completed |
+| 1-2 criteria ❌ or ⚠️ | Sprint PARTIAL → create fix tasks, DON'T mark completed |
+| 3+ criteria ❌ | Sprint FAIL → reassess, DON'T mark completed |
+
+### Step 5: Sprint Summary
+
+```markdown
+## Sprint S09 — Validation Result: PARTIAL
+
+### Passed (3/5)
+- ✅ Blog CRUD — fully functional
+- ✅ CMS admin — complete with DataTable
+- ✅ SEO metadata — auto-generated
+
+### Failed (1/5)
+- ❌ RSS feed — not implemented
+
+### Unverifiable (1/5)
+- ⚠️ LCP performance — requires deployment
+
+### Action
+- Created fix task: "Implement RSS feed at /feed.xml"
+- Sprint remains OPEN until RSS is complete
+- LCP deferred to post-deployment verification
+```
+
+## Event Emission
+
+```python
+bridge.emit_event("sprint.validation", {
+    "sprint": "S09",
+    "result": "partial",
+    "criteria_total": 5,
+    "criteria_passed": 3,
+    "criteria_failed": 1,
+    "criteria_unverifiable": 1,
+    "action": "created_fix_tasks",
+    "fix_tasks": ["Implement RSS feed"]
+})
+```
+
+## Integration
+
+- **quality-gates**: Tasks must pass Completion Gate BEFORE sprint validation runs
+- **roadmap-reassessment**: Failed sprint triggers reassessment
+- **verification-gate**: Sprint validation uses verification commands
+- **cost-tracking**: Sprint cost is part of the validation summary
+- **knowledge-persistence**: Record what worked/failed in KNOWLEDGE.md
+- **task-complete**: Sprint validation BLOCKS `/task-complete` for the sprint itself
+- **Flyee SaaS**: Sprint validation results visible in progress dashboard

package/core/skills/stuck-detection/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: stuck-detection
+description: Detects when the agent enters an infinite loop — repeating the same actions, failing the same way, or making zero progress. Uses a sliding-window pattern detector to identify cycles and break them before wasting budget.
+---
+
+# Stuck Detection
+
+> Detects and breaks infinite loops in agent execution.
+
+## Problem
+
+Without stuck detection, an agent can:
+- Retry the same failing command indefinitely
+- Edit → undo → re-edit the same file in a loop
+- Make the same search query repeatedly
+- Generate the same code that fails the same test
+
+Each iteration burns tokens and budget with zero progress.
+
+## Detection Algorithm
+
+### Sliding Window Pattern Detector
+
+Monitor the last N tool calls (window size = 10) for:
+
+```
+Pattern 1: EXACT REPEAT
+  Tool calls [i] == Tool calls [i-1] == Tool calls [i-2]
+  → Same tool, same arguments, 3+ times in a row
+
+Pattern 2: CYCLE
+  Sequence A-B-C-A-B-C detected
+  → Agent alternating between the same actions
+
+Pattern 3: ZERO PROGRESS
+  Last 5 tool calls produced no file changes
+  AND no new information was gathered
+  → Agent is "thinking" but not "doing"
+
+Pattern 4: FAIL-RETRY-FAIL
+  Same command fails → agent retries → same failure
+  → 3+ identical failures without changing approach
+```
+
+### Detection Thresholds
+
+| Pattern | Threshold | Confidence |
+|---------|-----------|------------|
+| Exact repeat | 3 consecutive | HIGH |
+| Cycle | 2 full cycles (6+ calls) | HIGH |
+| Zero progress | 5 calls, 0 changes | MEDIUM |
+| Fail-retry-fail | 3 identical failures | HIGH |
+
+## Response Protocol
+
+### Phase 1: Soft Intervention
+
+On first detection:
+
+```markdown
+⚠️ **Stuck Detection Triggered**
+
+Pattern: {pattern_type}
+Evidence: {last N tool calls summarized}
+Window: {call_count} calls, {time_elapsed}
+
+Attempting recovery: Retry with diagnostic prompt.
+```
+
+Inject a **diagnostic prompt** that:
+1. Summarizes what was attempted
+2. Explains WHY it's stuck
+3. Asks the agent to try a **different approach**
+
+### Phase 2: Hard Stop
+
+If soft intervention fails (same pattern recurs within 5 tool calls):
+
+```markdown
+🛑 **Stuck Detection — Hard Stop**
+
+The agent has been stuck in a loop for {call_count} calls.
+Pattern: {pattern_type}
+Estimated wasted cost: ${cost}
+
+Action: Pausing execution.
+Next steps:
+1. Review the session log
+2. Provide manual guidance
+3. Resume with `/execute`
+```
+
+### Phase 3: Escalation
+
+Emit event for Flyee SaaS:
+
+```json
+{
+  "event_type": "stuck_detection.triggered",
+  "payload": {
+    "task_id": "T-001",
+    "pattern": "fail_retry_fail",
+    "tool_calls_in_loop": 9,
+    "wasted_cost_usd": 0.45,
+    "intervention": "hard_stop",
+    "last_5_calls": [
+      "run_command: npm test",
+      "replace_file_content: src/utils.ts",
+      "run_command: npm test",
+      "replace_file_content: src/utils.ts",
+      "run_command: npm test"
+    ]
+  }
+}
+```
+
+## Implementation
+
+### For Prompt-Based Agents (Flyee approach)
+
+Since flyee-agent runs INSIDE the host runtime (not as a standalone app), stuck detection works through **skill instructions**:
+
+```markdown
+## Self-Monitoring Protocol
+
+You MUST monitor your own behavior for loops:
+
+After every 5 tool calls, ask yourself:
+1. Am I making progress? (new files, passing tests, new info)
+2. Am I repeating the same action? (same edit, same command)
+3. Have I changed approach since the last failure?
+
+If the answer to #1 is NO and #2 or #3 is YES:
+→ STOP. State what you're stuck on. Ask the user for guidance.
+
+DO NOT:
+- Retry the same command more than 2 times
+- Edit the same file more than 3 times for the same issue
+- Run the same failing test more than 2 times without changing the code
+```
+
+### For Bridge-Level Detection
+
+The `local_tracker.py` can implement pattern detection on the event log:
+
+```python
+def check_stuck(events, window=10):
+    recent = events[-window:]
+    
+    # Pattern 1: Exact repeat
+    if len(set(e['action'] for e in recent[-3:])) == 1:
+        return 'exact_repeat'
+    
+    # Pattern 4: Fail-retry-fail
+    failures = [e for e in recent if e.get('result') == 'failure']
+    if len(failures) >= 3:
+        cmds = [f['action'] for f in failures[-3:]]
+        if len(set(cmds)) == 1:
+            return 'fail_retry_fail'
+    
+    return None
+```
+
+## Integration
+
+- **cost-tracking**: Log wasted cost during stuck periods
+- **session-resilience**: Stuck detection can trigger session save
+- **knowledge-persistence**: Record what caused the loop in Lessons Learned
+- **task-complete**: Block completion if agent was stuck and didn't resolve
+- **Flyee SaaS**: Dashboard shows stuck incidents timeline (S-03)
+
+## Exclusions
+
+- **Research tasks**: Repeated searches are normal during research
+- **Interactive debugging**: User may ask to retry — that's not a loop
+- **Build/test cycles**: Edit → test → edit → test is normal IF the edits are different