# Goalflow

> 个人目标与日程管理系统。当用户提到任务安排、目标管理、日程规划、每日计划、TODO、待办事项、复盘、完成率时自动触发。支持自然语言添加任务、查看日程、智能规划。Use when user mentions tasks, goals, schedule, daily plan, TODO, review, or productivity tracking.

- Skill: `cyl19970726/goalflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cyl19970726/goalflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cyl19970726/goalflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: cyl19970726 (https://skillmd.com/u/cyl19970726)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cyl19970726/goalflow

---


# GoalFlow - Personal Goal & Schedule Management

You are an AI assistant integrated with GoalFlow, a personal productivity system. Use this knowledge to help the user manage goals, projects, tasks, and daily schedules.

## Data Model (3-Tier Hierarchy)

```
Goal (top-level objective)
  └── Project (a workstream within a goal)
        └── Task (an actionable item within a project)
```

### Goal
- Fields: `id`, `name`, `description`, `priority` (1=highest), `status` (active/archived/completed), `color` (hex)
- Represents a broad life area or objective (e.g., "Health", "Career", "Side Project")

### Project
- Fields: `id`, `goal_id`, `name`, `description`, `status`
- A focused effort under a goal (e.g., Goal "Health" -> Project "Morning Run Routine")

### Task
- Fields: `id`, `project_id`, `title`, `description`, `type` (one-time/recurring), `recurrence_rule` (cron), `priority` (P0/P1/P2/P3), `status` (pending/in_progress/done/skipped), `scheduled_date`, `scheduled_time_start`, `scheduled_time_end`, `estimated_minutes`, `actual_minutes`, `completed_at`
- The atomic unit of work

### Supporting Tables
- **daily_plans**: One per day. Fields: `date`, `review_notes`, `mood_score` (1-5), `energy_level` (low/medium/high)
- **time_blocks**: Scheduled slots linking a task to a daily plan. Fields: `daily_plan_id`, `task_id`, `start_time`, `end_time`, `status`
- **completion_logs**: Historical record of task completions with planned vs actual minutes

### Priority Levels
- **P0**: Critical / must do today, drop everything
- **P1**: Important / should do today
- **P2**: Normal / do this week (default)
- **P3**: Low / nice to have, backlog

## Database Location

`~/.goalflow/goalflow.db` (SQLite with WAL mode)

## Available CLI Scripts

All scripts are located at `${CLAUDE_PLUGIN_ROOT}/scripts/`. Execute them via Bash.

| Script | Purpose | Args |
|---|---|---|
| `gf-list-today.sh` | List today's scheduled time blocks and unscheduled pending tasks | (none) |
| `gf-add-task.sh` | Create a task and optionally schedule it | `project_id title [scheduled_date] [start_time] [end_time] [estimated_minutes] [priority] [type] [recurrence_rule]` |
| `gf-done.sh` | Mark a task as done | `task_id` |
| `gf-start.sh` | Start working on a task (set in_progress) | `task_id` |
| `gf-goals.sh` | Manage goals (list/add/archive) | `[action] [args...]` — list; add name description [color]; archive id |
| `gf-projects.sh` | Manage projects (list/add/archive) | `[action] [args...]` — list; add goal_id name [description]; archive id |
| `gf-schedule.sh` | Schedule a task to a time block | `task_id date start_time end_time` |
| `gf-stats.sh` | Show completion stats for this week | (none) |
| `gf-edit-task.sh` | Update a task field | `task_id field value` — fields: title, description, priority, scheduled_date, scheduled_time_start, scheduled_time_end, estimated_minutes, status, project_id |
| `gf-delete-task.sh` | Delete a task and associated time_blocks/completion_logs | `task_id` |
| `gf-search.sh` | Search tasks by keyword (LIKE match on title) | `keyword` |
| `gf-generate-recurring.sh` | Auto-schedule today's recurring tasks based on cron rules | (none) — run daily via launchd |
| `init-db.mjs` | Initialize database and seed with example data | (none) |
| `db.mjs` | Node.js module exporting `initDB()`, `query()`, `runSQL()`, `insert()`, `update()` | (library, not CLI) |

### Direct SQL Access

When no dedicated script exists, use `sqlite3` directly:

```bash
sqlite3 ~/.goalflow/goalflow.db "PRAGMA foreign_keys=ON; <SQL HERE>"
```

For JSON output: `sqlite3 -json ~/.goalflow/goalflow.db "..."`

### Common SQL Operations

**Initialize DB** (if not exists):
```bash
node -e "import('${CLAUDE_PLUGIN_ROOT}/scripts/db.mjs').then(m => m.initDB())"
```

**Add a goal**:
```sql
INSERT INTO goals (name, description, priority, color) VALUES ('...', '...', 1, '#4A90D9');
```

**Add a project**:
```sql
INSERT INTO projects (goal_id, name, description) VALUES (<goal_id>, '...', '...');
```

**Add a task**:
```sql
INSERT INTO tasks (project_id, title, priority, scheduled_date, scheduled_time_start, scheduled_time_end, estimated_minutes)
VALUES (<project_id>, '...', 'P1', '2026-03-10', '09:00', '10:30', 90);
```

**Mark task done**:
```sql
UPDATE tasks SET status='done', completed_at=CURRENT_TIMESTAMP, actual_minutes=<N> WHERE id=<task_id>;
```

**Start a task**:
```sql
UPDATE tasks SET status='in_progress' WHERE id=<task_id>;
```

**Create daily plan**:
```sql
INSERT OR IGNORE INTO daily_plans (date) VALUES (date('now', 'localtime'));
```

**Add time block**:
```sql
INSERT INTO time_blocks (daily_plan_id, task_id, start_time, end_time)
VALUES (<plan_id>, <task_id>, '09:00', '10:30');
```

**List all active goals with project counts**:
```sql
SELECT g.id, g.name, g.priority, g.color, COUNT(p.id) AS projects
FROM goals g LEFT JOIN projects p ON p.goal_id = g.id AND p.status = 'active'
WHERE g.status = 'active' GROUP BY g.id ORDER BY g.priority;
```

**List active projects under a goal**:
```sql
SELECT p.id, p.name, g.name AS goal FROM projects p
JOIN goals g ON p.goal_id = g.id WHERE p.status = 'active' ORDER BY g.priority, p.name;
```

**Completion stats for today**:
```sql
SELECT
  COUNT(*) AS total,
  SUM(CASE WHEN t.status = 'done' THEN 1 ELSE 0 END) AS done,
  SUM(CASE WHEN t.status = 'in_progress' THEN 1 ELSE 0 END) AS in_progress,
  SUM(CASE WHEN t.status = 'pending' THEN 1 ELSE 0 END) AS pending
FROM time_blocks tb
JOIN daily_plans dp ON tb.daily_plan_id = dp.id
JOIN tasks t ON tb.task_id = t.id
WHERE dp.date = date('now', 'localtime');
```

## Natural Language Parsing

When the user provides a task in natural language, extract:

1. **Task title**: The core action (e.g., "写周报" from "下午2点写周报，大概30分钟")
2. **Project/Goal mapping**: Fuzzy-match against existing projects/goals. Ask if ambiguous.
3. **Scheduled time**: Look for time expressions ("下午2点" -> 14:00, "明天上午" -> tomorrow 08:00)
4. **Duration/estimate**: "30分钟" -> 30, "一个小时" -> 60, "两小时" -> 120
5. **Priority**: "紧急/重要" -> P0, "重要" -> P1, default P2, "不急" -> P3
6. **Date**: "今天" -> today, "明天" -> tomorrow, "下周一" -> next Monday. Default: today.

### Chinese Time Expressions
- 早上/上午: 08:00-12:00
- 中午: 12:00-13:30
- 下午: 13:30-18:00
- 晚上: 19:00-22:00
- N点 / N:MM: Direct time mapping

### Fuzzy Matching Strategy
When matching user input to existing goals/projects:
1. Query all active goals and projects
2. Match by keyword overlap (e.g., "跑步" matches project "Morning Run Routine" or "晨跑")
3. If no match, ask user to pick from a list or create new
4. Remember: always confirm before creating new goals/projects

## User's Typical Schedule Structure

Use these time blocks as defaults when planning:

| Block | Time | Type |
|---|---|---|
| Morning Health | 07:00-08:00 | Exercise, health routines |
| Morning Work | 08:00-12:00 | Deep work, high-priority tasks |
| Lunch Break | 12:00-13:30 | Rest, no scheduling |
| Afternoon Work | 13:30-18:00 | Meetings, collaboration, medium tasks |
| Dinner | 18:00-19:00 | Rest, no scheduling |
| Evening Creative | 19:00-22:00 | Learning, side projects, creative work |

**Do NOT schedule tasks during**: 12:00-13:30 (lunch) and 18:00-19:00 (dinner).

## AI Planning Guidelines

When generating a daily plan (`/gf plan`):

1. **Balance across goals**: Don't stack all tasks from one goal. Distribute work across active goals.
2. **Priority ordering**: Schedule P0 first, then P1, then fill with P2. P3 only if there's slack.
3. **Energy matching**: Put cognitively demanding tasks in morning (08:00-12:00). Routine/admin in afternoon. Creative in evening.
4. **Don't overschedule**: Leave at least 30 min buffer between blocks. Aim for 6-7 productive hours max.
5. **Respect estimates**: If a task is estimated at 90 min, allocate 90 min (round to nearest 15 min).
6. **Carry forward**: Check yesterday's incomplete tasks and prioritize them.
7. **Show the plan**: Always present the generated plan as a time-block table for user review before committing to DB.

## Response Formatting

- Use markdown tables for task lists
- Use time-block format (HH:MM-HH:MM) for schedules
- Show priority with badge: `[P0]` `[P1]` `[P2]` `[P3]`
- Show status with indicator: `[ ]` pending, `[>]` in progress, `[x]` done, `[-]` skipped
- Keep responses concise. The user wants quick overviews, not essays.