Minna Workflow Tuning

Raw STATUS.md

# Minna Workflow Tuning

**Status:** 🟢 Active
**Phase:** Implementation Ready + Meta Tools Built
**Last Activity:** 2026-02-02 (Full meta run, 20 workflow ideas researched, community intel capture)

---

## 🎯 Project Scope (Merged)

This project now encompasses ALL workflow infrastructure work, merged from:
- **minna-workflow-tuning** (original) — Workflow ecosystem documentation, GitHub migration
- **workflow-overhaul** (merged in) — Taxonomy of agents/projects/skills/tasks, logging spec

### Three Pillars

| Pillar | What | Key Deliverable |
|--------|------|-----------------|
| **Taxonomy** | What things ARE | Agent/Project/Skill/Task classification |
| **Tracking** | Where things LIVE | GitHub + Portal + Todoist coexistence |
| **Tools** | How Minna HELPS | Enhanced skills with event logging |

---

## 🔧 Meta Tools Built (2026-02-02)

New self-improvement infrastructure for Minna system health and pattern compliance.

### Files Created

| File | Purpose |
|------|---------|
| `SYSTEM-PATTERNS.md` | 9 core patterns documented (skill+cron, project structure, label flow, etc.) |
| `config/capability-inventory.json` | Full system catalog (22 projects, 18 crons, 16+ skills by category) |
| `skills/minna/references/meta-analysis.md` | Enhanced minna meta skill with 5 analysis pillars |

### New Capabilities

| Trigger | What It Does |
|---------|--------------|
| `minna meta` | Full 7-phase self-analysis: config health, session logs, community intel (throttled), project audit, cron health, workflow research (subagents), recommendations. Includes self-reflection on Minna skill health. Offers to capture community intel as Todoist tasks. |
| `minna check` | Quick compliance scan: verifies STATUS.md exists, status badges valid, no stale blockers, config files correct |

**Note:** Workflow research (spawning subagents per Todoist idea) is now Phase 6 of `minna meta`, not a separate trigger. Batches 3-4 subagents at a time for responsible resource management.

### Session Updates (2026-02-02 evening)

**Minna Meta Enhancements:**
- ✅ Merged `minna meta workflow` into main skill (no separate trigger)
- ✅ Added web search throttling (2-sec delays, max 5 searches)
- ✅ Added Minna self-reflection phase (analyzes own skill health)
- ✅ Added community intel capture option (creates Todoist tasks from findings)
- ✅ Specified batch spawning (3-4 subagents at a time)
- ✅ Removed duplicate Minna Meta Weekly crons (had 3, now 1)

**First Full Run Results:**
- 20 workflow research subagents spawned and completed
- 5 community intel items captured to Todoist inbox
- All findings written back to source Todoist tasks
- Community sources: GitHub discussions, awesome-openclaw-skills repo, ClawdHub

### Cron Added

| Name | Schedule | Purpose |
|------|----------|---------|
| Minna Meta Weekly | Sundays 8pm PT | Automated weekly system health report |

### SYSTEM-PATTERNS.md Contents (Expanded)

Now documents 19 comprehensive sections:
1. **Core Architecture** — System diagram, component overview
2. **Project Patterns** — Creation, structure, lifecycle, STATUS.md template
3. **Task Patterns** — IDs, blockers, states, label flows
4. **Skill Patterns** — Creation, structure, SKILL.md template
5. **Cron Patterns** — When to create, schedule patterns, alignment
6. **Agent Patterns** — Types, spawning, coordinator pattern, context loading
7. **Integration Patterns** — MCP setup, OAuth, webhooks, API interaction
8. **State & Memory** — Types, formats, what to remember
9. **Logging & Observability** — What/where/how to log, debugging
10. **Notification & Messaging** — Channel selection, when to notify, formats
11. **Security & Permissions** — Hard boundaries, confirmations, data handling
12. **Error Recovery** — OAuth, rate limits, browser, network patterns
13. **Naming Conventions** — Files, sessions, tasks, crons, labels
14. **Documentation Standards** — Required docs, templates
15. **Lifecycle Management** — Project, skill, cron lifecycles
16. **Data Flows** — Todoist, project tracking, memory, research flows
17. **Resource Management** — Token budgets, API quotas, concurrency
18. **Compliance Checklist** — Checklists for project, skill, cron, integration
19. **Anti-Patterns** — What NOT to do

~25KB comprehensive documentation

### Capability Inventory Categories

**Projects (22):**
- website_ui: hippochat-website, minna-portal, 4guys, meeting-makers
- automation_pipeline: libby-to-kindle, relationship-archaeology, nvrbot-scraper
- bot_agent: nvrmnd-bot, minna-accounts
- knowledge_content: nvrmnd-kb, ai-advantage, podcast-monitoring, bookmarks
- infrastructure: project-deploy, workflow-tuning, google-docs-api
- review_cleanup: coding-projects, filing-cabinet, gmail-starred, libby

**Crons (18):** daily_rituals, periodic_data, monitoring, weekly, special_dates

**Skills (16+ minna modes):** Plus standalone skills (booklist-parser, weather, imsg, github, etc.)

---

## Key Decision: GitHub All-In (for code projects)

**Move ALL project/task tracking to GitHub Issues + PRs** for code-related work:
- Issues for tasks (replacing STATUS.md task sections)
- PRs for all changes (code, docs, everything)
- GitHub Projects for visualization (optional)
- Audit logs via GitHub activity
- Portal integration via Supabase mirroring

**Keep STATUS.md for:**
- Non-code work (research, personal admin)
- Narrative context and high-level overview
- Projects not yet migrated

---

## Research Complete ✅

| Document | Purpose | Location |
|----------|---------|----------|
| VISION-UNIFIED-WORKFLOW.md | Synthesized strategy | docs/ |
| RESEARCH-GITHUB-DASHBOARDS.md | GitHub tooling analysis | docs/ |
| SYNTHESIS-GITHUB-INTEGRATION.md | Integration architecture | docs/ |
| PROJECT-MIGRATION-MAP.md | Per-project migration plan | docs/ |
| SKILLS-AUDIT.md | Current skills inventory | docs/ |
| SPEC-SKILLS-LOGGING.md | Event logging schema | docs/ |
| TAXONOMY-DISCOVERY.md | Agent/Project/Skill/Task framework | docs/taxonomy/ |

---

## Implementation Roadmap

### Phase 1: Foundation (This Week)
- [x] Create Supabase `gh_*` tables ✅ (2026-02-02)
- [ ] Build webhook endpoint (`/api/webhooks/github`)
- [ ] Write backfill script
- [ ] Test with minna-portal repo

### Phase 2: Portal Integration (Week 2)
- [ ] Add GitHub queries to portal (`queries.ts`)
- [ ] Build GitHubIssuesPanel component
- [ ] Add project detail GitHub tab
- [ ] Test realtime updates

### Phase 3: Migration (Week 3)
- [ ] Migrate minna-portal tasks → GitHub Issues
- [ ] Migrate nvrmnd-bot tasks
- [ ] Migrate nvrbot-scraper tasks
- [ ] Update Minna morning skill for GitHub source

### Phase 4: Agent Infrastructure (Future)
- [ ] Create `/agents/` directory structure
- [ ] Design AGENT.md manifest format
- [ ] Reframe relationship-archaeology as agent
- [ ] Add agent dashboard to portal

---

## Taxonomy Summary

### Four Types of Work

| Type | Definition | Examples |
|------|------------|----------|
| **Agent** | Autonomous entity with identity/goals | Minna, RelArchaeologist |
| **Project** | Finite human-driven work | minna-portal, ai-advantage |
| **Skill** | Invokable capability | Calendar lookup, Todoist sync |
| **Task** | Atomic unit of work | "Deploy portal" |

### Misclassifications to Fix

| Current | Should Be | When |
|---------|-----------|------|
| relationship-archaeology | Agent | Phase 4 |
| nvrbot-scraper | Agent | Phase 4 |
| podcast-monitoring | Agent | Phase 4 |

---

## Tasks

### Active

| ID | Task | Status |
|----|------|--------|
| T50 | **Entity Schema Formalization** | 🔄 Implementation (Phases 0-6 complete, Portal integration pending) |

---

## T50: Entity Schema Formalization

**Goal:** Create formal JSON schemas for all Minna ecosystem entities, enabling validation, tooling, and Portal integration.

**Why This Matters:**
- Currently all patterns are "honor system" — documented but not enforced
- No validation catches drift from conventions
- Portal needs reliable structure for UI components (multiple choice answers, project questions, etc.)
- New entities risk inconsistency without schema guidance

---

### Phase 0: Audit (Completed 2026-02-02)

**Inventory discovered:**

| Entity | Count | Files |
|--------|-------|-------|
| project.config.json | 19 | All in /projects/*/ |
| progress.json | 6 | relationship-archaeology, minna-portal, hippochat-website, libby-to-kindle, 4guys, meeting-makers |
| *-state.json | 5 | heartbeat, podcast, daily-delight, iteration, nvrbot-monitor |
| SKILL.md | 7 | minna, booklist-parser, vercel-preview-deploy, register, libby, project-status, amber-brief |

**Field Analysis:**

**project.config.json (consistent):**
- Core: `name`, `slug`, `description`, `type`, `status`, `phase`
- Display: `display.dashboardPriority`, `display.showHealthIndicators`, `display.icon`
- Alerts: `alerts.staleAfterDays`, `alerts.waitingAlertDays`
- Tracking: polymorphic — `tracking.milestones[]` OR `tracking.metrics{}`
- Optional: `links`, `tags`, `monitoring`

**progress.json (polymorphic):**
- Type A (batch): `current.emailsProcessed`, `batches[]`, `velocity`
- Type B (milestone): `current.*`, `phases.*`, `extensions.*`
- Common: `project`, `target`, `current`

**State files (custom per use case):**
- heartbeat-state: timestamp fields for check tracking
- podcast-state: `seenEpisodes[]`, `notifiedEpisodes[]`
- daily-delight-state: `history[]`, `feedback{}`
- Pattern: last-run timestamps + domain-specific arrays/objects

**SKILL.md:**
- YAML frontmatter: `name`, `description` (required)
- Body: freeform markdown, varies by skill complexity

---

### Phase 1: Schema Definitions

Create JSON Schema files in `schemas/` directory:

| Schema | Defines | Key Fields | Notes |
|--------|---------|------------|-------|
| `project.config.schema.json` | Project configuration | slug, name, type, status, alerts, tracking | Core entity, well-defined |
| `progress.schema.json` | Progress tracking | project, target, current, velocity | **Polymorphic** — use oneOf for batch/milestone/phase |
| `status-md.schema.json` | STATUS.md structure | status badge, phases, tasks, blockers | Markdown — schema defines sections |
| `task.schema.json` | Task format | id [T#], title, status, blockers, dates | Embedded in STATUS.md |
| `skill.schema.json` | Skill manifest (YAML) | name, description | Frontmatter only — body is freeform |
| `cron.schema.json` | Cron job format | schedule, payload, sessionTarget | From OpenClaw spec |
| `state-file.base.schema.json` | Base for *-state.json | lastRun, notes | **Extensible** — domain fields vary |
| `agent.schema.json` | Agent manifest | identity, capabilities, permissions | Future — AGENT.md format |

### Phase 2: Validation Tooling

| Tool | Purpose | Implementation |
|------|---------|----------------|
| `scripts/validate-schema.ts` | CLI validator | `npx tsx scripts/validate-schema.ts <file>` |
| `minna check --schemas` | Minna integration | Validate all config files against schemas |
| Pre-commit hook (optional) | Prevent invalid commits | Run on *.config.json, *.schema.json |

### Phase 3: Migration & Updates

1. **Audit existing files** — List all files that should conform
2. **Fix non-conformant files** — Update to match schemas
3. **Update SYSTEM-PATTERNS.md** — Add schema references to each section
4. **Update capability-inventory.json** — Add schema field per entity type

### Phase 4: Generation & Templates

| Generator | Output | Use Case |
|-----------|--------|----------|
| `scripts/new-project.ts` | project.config.json + STATUS.md | `minna new project <name>` |
| `scripts/new-skill.ts` | SKILL.md + structure | `minna new skill <name>` |
| TypeScript types | `types/entities.ts` | Portal type safety |

### Phase 5: Portal Integration

**Key benefit:** Structured data for UI components

| Use Case | How Schemas Help |
|----------|------------------|
| Project questions | Schema defines valid answer types (multiple choice, text, date) |
| Task creation forms | Schema defines required/optional fields |
| Validation feedback | Real-time UI validation against schema |
| Auto-complete | Schema enums power dropdowns |

**Portal files to update:**
- `types/project.ts` — Generate from schema
- `types/task.ts` — Generate from schema
- `components/forms/*` — Schema-driven form generation

### Phase 6: Enforcement Mechanisms

**Goal:** Prevent drift and ensure ongoing compliance

| Mechanism | How | When |
|-----------|-----|------|
| Prompt guardrails | Entity Schema Rule in AGENTS.md | ✅ Already added |
| Validation in minna check | Run schema validation on all entity files | On demand |
| Weekly schema audit cron | Scan for non-conformant files, report drift | Weekly (Sundays) |
| Pre-creation validation | Generators validate before writing | On `minna new` |

**Cron added:** ✅
- `Schema Compliance Audit` (ID: `1beebb9a-f55f-4058-a49d-cbbcd36027ba`) — Sundays 7pm PT, runs `validate-all.ts`, reports issues to Telegram

**Skills/Crons audited for schema awareness:** ✅ (2026-02-03)
- All 24 crons reviewed — documented which create/read entities
- All 7 skills reviewed — documented schema needs
- Minna meta skill — schema validation integrated into audit phase
- Project creation flows — use generators with validation
- project-status skill — reads STATUS.md, should validate format

### Deliverables Checklist

- [x] Add Entity Schema Rule to AGENTS.md ✅
- [x] Add Entity Schema Rule to SYSTEM-PATTERNS.md ✅
- [x] Create `schemas/` directory ✅ (2026-02-03)
- [x] Write 8 core schemas ✅ (2026-02-03)
  - `project.config.schema.json` — Project configuration (polymorphic tracking)
  - `progress.schema.json` — Progress tracking (batch/milestone/phase via oneOf)
  - `state-file.base.schema.json` — Base for *-state.json (extensible)
  - `skill.schema.json` — SKILL.md YAML frontmatter
  - `task.schema.json` — Task format for STATUS.md
  - `cron.schema.json` — Cron job configuration
  - `agent.schema.json` — Agent manifest (AGENT.md)
  - `schemas/README.md` — Full documentation with examples
- [x] Build validation script ✅ (2026-02-03)
  - `scripts/validate-schema.ts` — Single file validation with auto-detection
  - `scripts/validate-all.ts` — Workspace-wide validation with summary report
- [x] Add `minna check --schemas` flag ✅ (2026-02-03) — documented in meta-analysis.md
- [x] Audit & fix existing files ✅ (2026-02-03) — validation passes for all 32 entities
- [x] Cron/Skill audit complete ✅ (2026-02-03) — Phase 5-6 done
  - 24 crons audited, entity creation/reading documented
  - 7 skills audited, schema needs identified
  - Weekly enforcement cron created (Schema Compliance Audit)
- [x] Create generators for new projects/skills ✅ (2026-02-03)
  - `scripts/new-project.ts` — Creates project with config, STATUS.md, progress.json
  - `scripts/new-skill.ts` — Creates skill with SKILL.md and references/
  - Added `minna new project <slug>` and `minna new skill <name>` triggers
  - Tested with test entities, validated against schemas
- [x] Generate TypeScript types for Portal ✅ (2026-02-02) — `types/entities.ts`
- [ ] Update Portal forms to be schema-driven

### Files to Create

```
schemas/
├── project.config.schema.json
├── progress.schema.json
├── status-md.schema.json
├── task.schema.json
├── skill.schema.json
├── cron.schema.json
├── state-file.schema.json
├── agent.schema.json
└── README.md (schema documentation)

scripts/
├── validate-schema.ts
├── new-project.ts
└── new-skill.ts

types/
└── entities.ts (generated from schemas)
```

---

### Backlog — Implementation

| ID | Task | Phase |
|----|------|-------|
| T2 | Build GitHub webhook endpoint | 1 |
| T3 | Write GitHub backfill script | 1 |
| T4 | Test webhook with minna-portal | 1 |
| T5 | Add GitHub queries to portal | 2 |
| T6 | Build GitHubIssuesPanel component | 2 |
| T7 | Migrate minna-portal to GitHub Issues | 3 |
| T8 | Update Minna skill for GitHub source | 3 |

### Backlog — Documentation

| ID | Task | Priority |
|----|------|----------|
| T10 | Create workflow reference architecture diagram | Medium |
| T11 | Document Todoist label/project taxonomy | Medium |
| T12 | Define quarterly planning protocol | Low |

### Backlog — Agent Infrastructure

| ID | Task | Priority |
|----|------|----------|
| T20 | Design agent registry format (AGENT.md) | Medium |
| T21 | Create `/agents/` directory structure | Medium |
| T22 | Reframe relationship-archaeology as agent | Low |
| T23 | Design agent dashboard for portal | Low |

### Done
- [x] Document workflow ecosystem (STATUS.md overview)
- [x] Map portal integration touchpoints
- [x] Research GitHub dashboard tools
- [x] Synthesis: GitHub integration architecture
- [x] Mapping: Walk all 17 projects through migration
- [x] Taxonomy: Agent/Project/Skill/Task framework
- [x] Skills logging spec (JSONL format)
- [x] Skills audit & interoperability map
- [x] **Merge workflow-overhaul into this project** ✅
- [x] **T1: Create Supabase gh_* tables** ✅ (2026-02-02)
  - Created: gh_repos, gh_issues, gh_prs, gh_events tables
  - Views: gh_open_issues_by_project, gh_open_prs_by_project, gh_project_stats
  - RLS policies and realtime enabled
  - Migration: 008_github_sync.sql
- [x] **T30: Enhanced minna meta skill** ✅ (2026-02-02)
  - 5 analysis pillars: self-analysis, community intel, project audit, cron health, gap analysis
  - Parses session transcripts for errors/patterns
  - Searches OpenClaw community for tips
  - Created: `skills/minna/references/meta-analysis.md`
- [x] **T31: SYSTEM-PATTERNS.md** ✅ (2026-02-02)
  - 9 core patterns documented
  - Compliance checklist for new additions
  - Anti-patterns section
  - Architecture diagram
  - Created: `/SYSTEM-PATTERNS.md` (workspace root)
- [x] **T32: Capability inventory** ✅ (2026-02-02)
  - Full system catalog (projects, crons, skills)
  - Categories and patterns documented
  - Created: `config/capability-inventory.json`
- [x] **T33: minna check trigger** ✅ (2026-02-02)
  - Lightweight compliance scan
  - Verifies STATUS.md, badges, blockers, config files
- [x] **T34: Minna Meta Weekly cron** ✅ (2026-02-02)
  - Schedule: Sundays 8pm PT
  - Automated system health reporting
- [x] **T35: Expanded SYSTEM-PATTERNS.md** ✅ (2026-02-02)
  - 19 sections covering all system patterns
  - Project, Task, Skill, Cron, Agent creation patterns
  - Integration, State, Logging, Security patterns
  - Naming conventions, Documentation standards
  - Lifecycle management, Data flows, Resource management
  - Compliance checklist, Anti-patterns
  - ~25KB comprehensive documentation
- [x] **T36: Workflow Ideas Research Mode** ✅ (2026-02-02)
  - New trigger: `minna meta workflow` / `minna research workflow`
  - Pulls tasks from Todoist project "Workflow overhaul 2026" (ID: 6fr57r9qmcvRjQGh)
  - **Only processes tasks IN a section** (27 unsectioned tasks skipped, 12 sectioned eligible)
- [x] **T37: Meta skill consolidation** ✅ (2026-02-02)
  - Merged `minna meta workflow` into main `minna meta` (Phase 6)
  - Added web search throttling (2-sec delays)
  - Added Minna self-reflection phase
  - Removed duplicate Minna Meta Weekly crons (3 → 1)
- [x] **T38: Full workflow research run** ✅ (2026-02-02)
  - 20 subagents spawned for all eligible workflow ideas
  - All findings written to Todoist task descriptions
  - Topics: Strava, Spotify, ramble mode, layered agents, Mac Automator, Linux VM, deploy skill, file org, email processing, people workflow, backlog review, Gemini browsing, etc.
- [x] **T39: Community intel capture** ✅ (2026-02-02)
  - Added option to capture community intel as Todoist tasks
  - Created 5 tasks from GitHub discussions + awesome-openclaw-skills repo
  - Updated skill to offer this at end of every meta run
- [x] **T40: Batch spawning guidance** ✅ (2026-02-02)
  - Updated skill to batch 3-4 subagents at a time
  - Process ALL eligible tasks, not arbitrary subset
  - Spawns one subagent per task (fresh context each)
  - Skips already-researched tasks (>500 chars or has research header)
  - Each subagent reads SYSTEM-PATTERNS.md + capability-inventory.json
  - Includes "Clarifying Questions" section for ambiguous tasks
  - Writes findings back to Todoist task description
  - Coordinator compiles summary with themes, quick wins, priorities

---

## Enhancement Ideas (Top 10)

*Moved from original STATUS.md — workflow improvements for future consideration*

1. **🎯 Capacity Meter & Energy Tracking** — Daily energy (1-5), visual capacity meter
2. **📊 Weekly OKR Progress Dashboard** — Visual progress bars, velocity alerts
3. **🧘 Parts Check-In Integration (IFS)** — Morning prompts, pattern tracking
4. **🎲 Smart Frog Suggestions** — AI-suggested frogs with reasoning
5. **📅 Calendar-Aware Shortlist Builder** — Available work blocks, meeting warnings
6. **🔄 Rollover Intelligence** — Track rolled-over tasks, suggest rescope/kill
7. **📧 VIP Inbox Digest** — Morning summary with age indicators
8. **🏃 Streak & Momentum Tracking** — Beyond frogs, habit heatmaps
9. **🎭 Context Switching Cost Tracker** — Focus blocks vs scattered time
10. **📝 Decision Journal Integration** — Capture decisions, link to OKRs

---

## Key Files

### This Project
- `STATUS.md` — This file
- `project.config.json` — Project configuration
- `docs/VISION-UNIFIED-WORKFLOW.md` — Synthesized strategy (read this first!)
- `docs/taxonomy/TAXONOMY-DISCOVERY.md` — Classification framework
- `docs/SYNTHESIS-GITHUB-INTEGRATION.md` — Full implementation spec
- `docs/PROJECT-MIGRATION-MAP.md` — Per-project analysis
- `docs/SPEC-SKILLS-LOGGING.md` — Event logging schema
- `docs/SKILLS-AUDIT.md` — Current skills inventory
- `docs/RESEARCH-GITHUB-DASHBOARDS.md` — GitHub tooling research

### Meta Tools (New 2026-02-02)
- `/SYSTEM-PATTERNS.md` — 9 core patterns, compliance checklist, architecture diagram
- `config/capability-inventory.json` — Full system catalog (projects, crons, skills)
- `skills/minna/references/meta-analysis.md` — Enhanced minna meta skill

### Related
- `skills/minna/SKILL.md` — Minna skill definition (updated with minna check trigger)
- `projects/minna-portal/STATUS.md` — Portal project
- `AGENTS.md` — Agent behavior guidelines (to update with taxonomy)

---

*Created: 2026-02-02 | Merged: 2026-02-02*