flyee 0.1.0 → 0.2.0

package/core/skills/token-profiles/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: token-profiles
+description: Token optimization profiles that coordinate model selection, context compression, and phase skipping. Three modes — budget (40-60% savings), balanced (10-20%), quality (full power). Complexity-based routing automatically classifies tasks and selects appropriate models.
+---
+
+# Token Profiles
+
+> Coordinate token optimization across the entire workflow.
+
+## Purpose
+
+Not every task needs the most expensive model. Documentation tasks don't need Opus. Simple bug fixes don't need 200K context. Token profiles let you trade quality for cost (or vice versa) with a single setting.
+
+## Configuration
+
+In `.flyee/config.json`:
+
+```json
+{
+  "token_profile": "balanced"
+}
+```
+
+## Profiles
+
+| Profile | Token Savings | When to Use |
+|---------|--------------|-------------|
+| `budget` | 40-60% | Personal projects, prototyping, learning |
+| `balanced` | 10-20% | Normal development (default) |
+| `quality` | 0% | Production features, complex architecture |
+
+### Budget Profile
+
+```yaml
+token_profile: budget
+behavior:
+  model_tier: cheap            # Use cheapest available model
+  context_loading: minimal     # Load only essential files
+  skip_phases:
+    - research                 # Skip research phase
+    - reassessment             # Skip roadmap reassessment
+  verification: advisory       # Log warnings, don't block
+  knowledge_injection: rules_only  # Only inject rules, not patterns
+```
+
+### Balanced Profile (Default)
+
+```yaml
+token_profile: balanced
+behavior:
+  model_tier: standard         # Use standard model
+  context_loading: standard    # Load relevant files
+  skip_phases:
+    - slice_research           # Skip per-slice research (project research still runs)
+  verification: enforced       # Block on failures
+  knowledge_injection: full    # Inject rules + patterns + recent lessons
+```
+
+### Quality Profile
+
+```yaml
+token_profile: quality
+behavior:
+  model_tier: premium          # Use best available model
+  context_loading: comprehensive  # Load all related files
+  skip_phases: []              # No phase skipping
+  verification: strict         # All checks + manual review suggestions
+  knowledge_injection: full    # Everything
+  extra:
+    - dual_review              # Review own output before committing
+    - extended_planning        # Longer planning phase
+```
+
+## Complexity-Based Model Routing
+
+Automatically classify tasks by complexity and route to appropriate models:
+
+### Classification Heuristics
+
+```
+SIMPLE (use cheap model):
+  - Documentation updates
+  - Config file changes
+  - Single-file edits < 50 lines
+  - Adding comments or logs
+  - Rename/move operations
+
+STANDARD (use standard model):
+  - Multi-file feature implementation
+  - Bug fixes requiring investigation
+  - Test writing
+  - Refactoring within a module
+
+COMPLEX (use premium model):
+  - Architectural changes
+  - Cross-module refactoring
+  - Security-sensitive code
+  - Performance optimization
+  - Database schema changes
+```
+
+### Classification Signals
+
+| Signal | Weight | Example |
+|--------|--------|---------|
+| File count | 0.3 | 1 file = simple, 5+ = complex |
+| Keyword analysis | 0.3 | "refactor architecture" = complex |
+| Test requirements | 0.2 | No tests = simple, integration tests = complex |
+| Domain sensitivity | 0.2 | Auth/payment = complex, docs = simple |
+
+### Model Tier Mapping
+
+| Tier | Gemini | Claude | OpenAI | OpenRouter |
+|------|--------|--------|--------|------------|
+| `cheap` | Flash | Haiku | GPT-4o-mini | DeepSeek |
+| `standard` | Pro | Sonnet | GPT-4o | Sonnet via OR |
+| `premium` | Ultra | Opus | o1 | Opus via OR |
+
+> **Note:** Actual model names depend on the runtime. This maps concepts, not specific model IDs.
+
+## Budget Pressure
+
+As costs approach the budget ceiling, progressively downgrade:
+
+| Budget Used | Action |
+|-------------|--------|
+| < 50% | Normal operation per profile |
+| 50-75% | Suggest cheaper model for simple tasks |
+| 75-90% | Force cheap model for non-critical tasks |
+| > 90% | Force cheap model for ALL tasks + warn user |
+
+### Pressure Event
+
+```python
+bridge.emit_event("cost.budget_pressure", {
+    "sprint": "S09",
+    "budget_used_pct": 78,
+    "pressure_level": "medium",
+    "action": "force_cheap_for_simple",
+    "current_profile": "balanced"
+})
+```
+
+## Integration
+
+- **cost-tracking**: Uses budget data to trigger pressure
+- **skill-discovery**: Profiles affect which skills are loaded (budget = fewer)
+- **context-budget**: Profiles set the effective context window size
+- **quality-gates**: Quality profile enables stricter gates
+- **Flyee SaaS**: Profile selection and model routing visible in cost dashboard

package/core/skills/unique-ids/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: unique-ids
+description: Unique ID generation for sprints, phases, tasks, and decisions. Avoids collision in team environments. Format uses short prefixes + random suffix for human-readability.
+---
+
+# Unique IDs
+
+> Collision-free identifiers for team environments.
+
+## Problem
+
+Sequential IDs (`S01`, `T03`) collide when multiple developers work on the same project. Developer A creates `S01`, Developer B creates `S01` — merge conflict.
+
+## ID Format
+
+```
+{prefix}-{short-hash}
+
+Examples:
+  S-a3f8     → Sprint
+  P-7c2e     → Phase
+  T-b4d1     → Task
+  D-9e5f     → Decision
+  E-1a2b     → Event
+```
+
+### Format Details
+
+| Component | Description |
+|-----------|-------------|
+| Prefix | `S` (Sprint), `P` (Phase), `T` (Task), `D` (Decision), `E` (Event) |
+| Hash | 4 hex characters from `crypto.randomBytes(2).toString('hex')` |
+
+4 hex chars = 65,536 combinations per prefix. Collision probability:
+- 10 items: ~0.07%
+- 100 items: ~7%
+- 1000 items: ~100% (would need longer hashes)
+
+For projects with >500 items of same type, extend to 6 hex chars (16M combinations).
+
+## Generation
+
+### In Python (bridge/local_tracker.py)
+
+```python
+import secrets
+
+def generate_id(prefix: str) -> str:
+    """Generate a unique short ID with prefix."""
+    suffix = secrets.token_hex(2)
+    return f"{prefix}-{suffix}"
+
+# Usage
+task_id = generate_id("T")    # "T-b4d1"
+sprint_id = generate_id("S")  # "S-a3f8"
+```
+
+### In JavaScript (installer/scripts)
+
+```javascript
+import { randomBytes } from 'crypto';
+
+function generateId(prefix) {
+  const suffix = randomBytes(2).toString('hex');
+  return `${prefix}-${suffix}`;
+}
+```
+
+## When to Generate
+
+| Entity | Generator | Storage |
+|--------|-----------|---------|
+| Sprint | Agent (during `/plan`) | `.flyee/STATE.md` |
+| Phase | Agent (during planning) | `.flyee/STATE.md` |
+| Task | `bridge.create_task()` | `.flyee/tasks.json` |
+| Decision | `bridge.create_decision()` | `.flyee/DECISIONS.md` |
+| Event | `bridge.emit_event()` | `.flyee/events.jsonl` |
+
+## Collision Handling
+
+If a generated ID already exists in the local store:
+
+```python
+def generate_unique_id(prefix: str, existing_ids: set) -> str:
+    """Generate a unique ID, retrying on collision."""
+    for _ in range(10):
+        new_id = generate_id(prefix)
+        if new_id not in existing_ids:
+            return new_id
+    # Fallback: use 6 chars
+    return f"{prefix}-{secrets.token_hex(3)}"
+```
+
+## Backward Compatibility
+
+Old sequential IDs (`S01`, `T03`) remain valid. The system accepts both formats:
+
+```python
+def normalize_id(raw_id: str) -> str:
+    """Accept both old (S01) and new (S-a3f8) formats."""
+    if '-' in raw_id:
+        return raw_id  # New format
+    return raw_id      # Old format (passthrough)
+```
+
+## Integration
+
+- **state-machine**: Uses unique IDs for sprint/phase hierarchy
+- **cost-tracking**: Logs reference task IDs
+- **session-resilience**: Session lock includes unique session ID
+- **bridge**: `create_task()` auto-generates unique ID
+- **Flyee SaaS**: Maps local IDs to Notion page IDs during sync

package/core/templates/RUNTIME.template.md

@@ -0,0 +1,41 @@
+# RUNTIME
+
+> Auto-maintained by flyee. Documents the runtime context of this project.
+> Updated when services, endpoints, or environment variables change.
+
+## Environment Variables
+
+| Variable | Purpose | Required | Default |
+|----------|---------|----------|---------|
+| `DATABASE_URL` | Database connection string | Yes | - |
+| `API_BASE_URL` | Backend API base URL | Yes | `http://localhost:3001` |
+| `NODE_ENV` | Runtime environment | No | `development` |
+
+## Services
+
+| Service | URL | Port | Health Check |
+|---------|-----|------|-------------|
+| Frontend | `http://localhost:3000` | 3000 | `GET /` |
+| Backend API | `http://localhost:3001` | 3001 | `GET /health` |
+| Database | `localhost:5432` | 5432 | `pg_isready` |
+
+## External APIs
+
+| API | Base URL | Auth | Docs |
+|-----|----------|------|------|
+| - | - | - | - |
+
+## Commands
+
+| Action | Command |
+|--------|---------|
+| Dev server | `npm run dev` |
+| Build | `npm run build` |
+| Test | `npm run test` |
+| Lint | `npm run lint` |
+| Database migrate | `npm run db:migrate` |
+
+## Notes
+
+- Add project-specific runtime context here
+- This file is read by the agent at session start to understand the deployment context

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flyee",
-  "version": "0.1.0",
-  "description": "AI Agent Framework — 21 specialist agents, 65+ skills, 40+ workflows. All runtimes.",
+  "version": "0.2.0",
+  "description": "AI Agent Framework — 22 specialist agents, 81 skills, 44 workflows. All runtimes.",
   "license": "MIT",
   "author": "Bruno Santana <bruno@flyee.dev>",
   "repository": {