@geekbeer/minion 2.5.0 → 2.6.0

package/rules/minion.md

@@ -3,6 +3,23 @@
 You are running on a Minion VPS managed by the @geekbeer/minion package.
 A local Agent API server runs at `http://localhost:3001` and a CLI tool `minion-cli` is available.
 
+## Architecture: Project / Workflow / Routine
+
+```
+Project (組織・課金単位)
+├── Context (markdown, PMが更新)
+├── Members (minion + role)
+└── Workflows (何をするか, スケジュールなし)
+
+Minion
+└── Routines (いつ・何を, cron付き)
+```
+
+- **Workflow** はプロジェクトスコープ。「何をするか」を定義。スケジュールは持たない。
+- **Routine** はミニオンスコープ。「いつ・何を」を定義。cron_expression を持ち、自律トリガーする。
+- ミニオンは複数プロジェクトに `pm` または `engineer` として参加できる。
+- ワークフローは直接トリガーされず、ルーティン経由で実行される（`project-workflow-check` スキル）。
+
 ## CLI Commands
 
 ```bash
@@ -35,7 +52,7 @@ Authentication: `Authorization: Bearer $API_TOKEN` header (except where noted).
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/list-skills` | List local deployed skills |
-| DELETE | `/api/skills/:name` | Delete local skill |
+| DELETE | `/api/skills/:name` | Delete a local skill |
 | POST | `/api/skills/push/:name` | Push local skill to HQ |
 | POST | `/api/skills/fetch/:name` | Fetch skill from HQ and deploy locally |
 | GET | `/api/skills/remote` | List skills on HQ |
@@ -44,23 +61,26 @@ Authentication: `Authorization: Bearer $API_TOKEN` header (except where noted).
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/workflows` | List all workflows with next_run |
-| POST | `/api/workflows` | Receive/upsert workflows from HQ |
+| GET | `/api/workflows` | List all local workflows with next_run |
+| POST | `/api/workflows` | Receive/upsert workflows (from HQ or local) |
 | POST | `/api/workflows/push/:name` | Push local workflow to HQ |
 | POST | `/api/workflows/fetch/:name` | Fetch workflow from HQ and deploy locally (+ pipeline skills) |
 | GET | `/api/workflows/remote` | List workflows on HQ |
-| PUT | `/api/workflows/:id/schedule` | Update workflow schedule (cron_expression, is_active) |
-| DELETE | `/api/workflows/:id` | Remove workflow |
+| PUT | `/api/workflows/:id/schedule` | **Legacy.** Update cron_expression/is_active. 新アーキではRoutine側で管理 |
+| DELETE | `/api/workflows/:id` | Remove a local workflow |
 | POST | `/api/workflows/trigger` | Manual trigger. Body: `{workflow_id}` |
 
+> **Note:** 新アーキテクチャでは Workflow にスケジュールがなく、Routine の cron で自律トリガーする設計。
+> `PUT /api/workflows/:id/schedule` はレガシー互換で残っているが、新規利用は非推奨。
+
 ### Executions
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/executions` | List execution history (?limit=50) |
+| GET | `/api/executions` | List execution history (`?limit=50`, `?workflow_id=`) |
 | GET | `/api/executions/:id` | Get single execution |
-| GET | `/api/executions/:id/log` | Get execution log content |
-| POST | `/api/executions/:id/outcome` | Report outcome (no auth). Body: `{outcome}` |
+| GET | `/api/executions/:id/log` | Get execution log content (`?tail=N`) |
+| POST | `/api/executions/:id/outcome` | Report outcome (no auth). Body: `{outcome, summary?, details?}` |
 
 Outcome values: `success`, `failure`, `partial`
 
@@ -69,13 +89,25 @@ Outcome values: `success`, `failure`, `partial`
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/terminal/sessions` | List tmux sessions |
-| POST | `/api/terminal/send` | Send keys. Body: `{session, keys}` |
-| POST | `/api/terminal/create` | Create session. Body: `{name, command?}` |
+| POST | `/api/terminal/send` | Send keys. Body: `{session, input?, enter?, special?}` |
+| POST | `/api/terminal/create` | Create session. Body: `{name?, command?}` |
 | POST | `/api/terminal/kill` | Kill session. Body: `{session}` |
-| GET | `/api/terminal/capture` | Capture pane content. Query: `?session=` |
+| GET | `/api/terminal/capture` | Capture pane content. Query: `?session=&lines=100` |
 | GET | `/api/terminal/ttyd/status` | ttyd process status |
-| POST | `/api/terminal/ttyd/start` | Start ttyd. Body: `{session}` |
-| POST | `/api/terminal/ttyd/stop` | Stop ttyd. Body: `{session}` |
+| POST | `/api/terminal/ttyd/start` | Start ttyd for session. Body: `{session}` |
+| POST | `/api/terminal/ttyd/stop` | Stop ttyd for session. Body: `{session}` |
+| POST | `/api/terminal/ttyd/stop-all` | Stop all ttyd processes |
+
+### Files
+
+Files are stored in `~/files/`. Max upload size: 50MB.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/files` | List files in directory. Query: `?path=subdir` |
+| GET | `/api/files/*` | Download a file |
+| POST | `/api/files/*` | Upload a file (Content-Type: `application/octet-stream`) |
+| DELETE | `/api/files/*` | Delete a file or directory |
 
 ### Commands
 
@@ -86,6 +118,103 @@ Outcome values: `success`, `failure`, `partial`
 
 Available commands: `restart-agent`, `update-agent`, `restart-display`, `status-services`
 
+## HQ API Endpoints (https://<HQ_URL>)
+
+Authentication: `Authorization: Bearer $API_TOKEN` header.
+Base path: All endpoints are prefixed with `/api/minion` by the agent's API client.
+
+### Projects
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/me/projects` | 参加プロジェクト一覧（role 含む） |
+
+Response:
+```json
+[
+  {
+    "id": "uuid",
+    "name": "project-name",
+    "description": "...",
+    "github_owner": "org",
+    "github_repo": "repo",
+    "role": "pm",
+    "created_at": "...",
+    "updated_at": "..."
+  }
+]
+```
+
+`role` is either `"pm"` (project manager) or `"engineer"`.
+
+### Project Context
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/me/project/[id]/context` | プロジェクトコンテキスト取得 |
+| PUT | `/api/minion/me/project/[id]/context` | コンテキスト更新（PM のみ） |
+
+PUT body: `{ "content": "markdown string" }`
+
+### Workflows (project-scoped)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/workflows` | 参加プロジェクトのワークフロー一覧 |
+
+Response:
+```json
+{
+  "workflows": [
+    {
+      "name": "workflow-name",
+      "pipeline_skill_names": ["skill-1", "skill-2"],
+      "content": "...",
+      "project_id": "uuid",
+      "created_at": "..."
+    }
+  ]
+}
+```
+
+### Routines (minion-scoped)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/routines` | 自分のルーティン一覧 |
+
+Response:
+```json
+[
+  {
+    "id": "uuid",
+    "name": "routine-name",
+    "pipeline_skill_names": ["skill-1", "execution-report"],
+    "content": "...",
+    "is_active": true,
+    "cron_expression": "0 9 * * 1-5",
+    "last_run": "...",
+    "next_run": "...",
+    "created_at": "...",
+    "updated_at": "..."
+  }
+]
+```
+
+### Skills
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/skills` | HQ に登録されたスキル一覧 |
+| GET | `/api/minion/skills/[name]` | スキル詳細取得（content, references 含む） |
+| POST | `/api/minion/skills` | スキル登録/更新 |
+
+### Execution Reporting
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/minion/execution` | 実行状況を HQ に報告 |
+
 ## Environment Variables
 
 | Variable | Description |
@@ -125,7 +254,8 @@ When not configured, the agent runs in standalone mode and HQ-dependent features
 
 ## Workflow Structure
 
-Workflows are stored locally in `workflows.json`. Each workflow object:
+Workflows are project-scoped and fetched from HQ via `GET /api/minion/workflows`.
+They are also stored locally in `workflows.json`. Each workflow object:
 
 ```json
 {
@@ -133,9 +263,7 @@ Workflows are stored locally in `workflows.json`. Each workflow object:
   "name": "my-workflow",
   "pipeline_skill_names": ["skill-1", "skill-2", "execution-report"],
   "content": "Markdown description of the workflow",
-  "cron_expression": "0 9 * * 1-5",
-  "is_active": true,
-  "last_run": "2026-02-10T00:00:00.000Z"
+  "project_id": "uuid"
 }
 ```
 
@@ -145,38 +273,7 @@ Workflows are stored locally in `workflows.json`. Each workflow object:
 | `name` | string | Slug identifier (`/^[a-z0-9-]+$/`) |
 | `pipeline_skill_names` | string[] | Ordered skill names to execute |
 | `content` | string | Markdown body describing the workflow |
-| `cron_expression` | string | Cron schedule (empty = manual only) |
-| `is_active` | boolean | Whether cron scheduling is enabled |
-| `last_run` | string\|null | ISO timestamp of last execution |
-
-### Creating a workflow locally
-
-Use `POST /api/workflows` to create/update workflows:
-
-```bash
-curl -X POST http://localhost:3001/api/workflows \
-  -H "Authorization: Bearer $API_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "workflows": [{
-      "id": "'$(uuidgen)'",
-      "name": "my-workflow",
-      "pipeline_skill_names": ["my-skill", "execution-report"],
-      "content": "Description of what this workflow does",
-      "cron_expression": "",
-      "is_active": false
-    }]
-  }'
-```
-
-Then activate with a schedule:
-
-```bash
-curl -X PUT http://localhost:3001/api/workflows/<id>/schedule \
-  -H "Authorization: Bearer $API_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"cron_expression": "0 9 * * 1-5", "is_active": true}'
-```
+| `project_id` | string | UUID of the parent project |
 
 ### Syncing workflows with HQ
 
@@ -186,10 +283,55 @@ curl -X PUT http://localhost:3001/api/workflows/<id>/schedule \
 
 Pipeline skills must be deployed locally (in `~/.claude/skills/`) before pushing a workflow.
 
-## Workflow Execution
+## Routine Structure
 
-Workflows run on cron schedules. Each execution:
+Routines are minion-scoped and fetched from HQ via `GET /api/minion/routines`.
+They are also stored locally in `routines.json`. Each routine object:
+
+```json
+{
+  "id": "uuid",
+  "name": "morning-work",
+  "pipeline_skill_names": ["project-workflow-check", "execution-report"],
+  "content": "Markdown description of the routine",
+  "cron_expression": "0 9 * * 1-5",
+  "is_active": true,
+  "last_run": "2026-02-10T09:00:00.000Z",
+  "next_run": "2026-02-11T09:00:00.000Z"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | UUID (auto-generated) |
+| `name` | string | Slug identifier (`/^[a-z0-9-]+$/`) |
+| `pipeline_skill_names` | string[] | Ordered skill names to execute |
+| `content` | string | Markdown body describing the routine |
+| `cron_expression` | string | Cron schedule (empty = manual only) |
+| `is_active` | boolean | Whether cron scheduling is enabled |
+| `last_run` | string\|null | ISO timestamp of last execution |
+| `next_run` | string\|null | ISO timestamp of next scheduled run |
+
+## Routine Execution
+
+Routines run on cron schedules. Each execution:
 1. Creates a tmux session
 2. Runs skills in pipeline order via `claude --dangerously-skip-permissions`
 3. Appends `execution-report` skill to report outcome
-4. Environment variables `MINION_EXECUTION_ID`, `MINION_WORKFLOW_ID`, `MINION_WORKFLOW_NAME` are available during execution
+4. Environment variables `MINION_EXECUTION_ID`, `MINION_ROUTINE_ID`, `MINION_ROUTINE_NAME` are available during execution
+
+### Workflow Execution via Routine
+
+ワークフローは `project-workflow-check` システムスキルを通じてルーティンから実行される:
+
+```
+ルーティン: "morning-work" (cron: 0 9 * * 1-5)
+  pipeline: [project-workflow-check, execution-report]
+    ↓
+  project-workflow-check:
+    1. GET /api/minion/me/projects → 参加プロジェクト一覧
+    2. GET /api/minion/workflows → active なワークフロー一覧
+    3. 各ワークフローの pipeline を順に実行
+    ↓
+  execution-report → HQ に結果報告
+```

package/server.js

@@ -13,6 +13,8 @@ const fastify = require('fastify')({ logger: true })
 const { config, validate, isHqConfigured } = require('./config')
 const workflowRunner = require('./workflow-runner')
 const workflowStore = require('./workflow-store')
+const routineRunner = require('./routine-runner')
+const routineStore = require('./routine-store')
 
 const { registerRoutes, setOffline, getProcessManager, getAllowedCommands } = require('./routes')
 const { cleanupTtyd, killStaleTtydProcesses } = require('./routes/terminal')
@@ -31,8 +33,9 @@ async function shutdown(signal) {
 
   setOffline()
 
-  // Stop workflow runner
+  // Stop workflow and routine runners
   workflowRunner.stopAll()
+  routineRunner.stopAll()
 
   // Stop terminal proxy and all ttyd processes
   stopTerminalProxy()
@@ -164,6 +167,17 @@ async function start() {
       console.error('[Server] Failed to load cached workflows:', err.message)
     }
 
+    // Load cached routines and start routine runner
+    try {
+      const cachedRoutines = await routineStore.load()
+      if (cachedRoutines.length > 0) {
+        console.log(`[Server] Loading ${cachedRoutines.length} cached routines`)
+        routineRunner.loadRoutines(cachedRoutines)
+      }
+    } catch (err) {
+      console.error('[Server] Failed to load cached routines:', err.message)
+    }
+
     if (isHqConfigured()) {
       console.log(`[Server] HQ URL: ${config.HQ_URL}`)
     } else {

package/workflow-runner.js

@@ -100,6 +100,7 @@ async function executeWorkflowSession(workflow, executionId, skillNames) {
 
   // Extend PATH to include common CLI installation locations
   const additionalPaths = [
+    path.join(homeDir, 'bin'),
     path.join(homeDir, '.npm-global', 'bin'),
     path.join(homeDir, '.local', 'bin'),
     path.join(homeDir, '.claude', 'bin'),

package/workflow-store.js

@@ -82,7 +82,7 @@ async function findByName(name) {
  * Upsert a workflow by name.
  * If exists: updates definition only (preserves schedule/local state).
  * If new: creates with inactive schedule.
- * @param {object} workflowData - { name, pipeline_skill_names, content }
+ * @param {object} workflowData - { name, pipeline_skill_names, content, project_id }
  * @returns {Promise<Array>} Updated workflows array
  */
 async function upsertByName(workflowData) {
@@ -96,12 +96,16 @@ async function upsertByName(workflowData) {
     if (workflowData.content !== undefined) {
       workflows[index].content = workflowData.content
     }
+    if (workflowData.project_id !== undefined) {
+      workflows[index].project_id = workflowData.project_id
+    }
   } else {
     workflows.push({
       id: crypto.randomUUID(),
       name: workflowData.name,
       pipeline_skill_names: workflowData.pipeline_skill_names,
       content: workflowData.content || '',
+      project_id: workflowData.project_id || null,
       cron_expression: '',
       is_active: false,
       last_run: null,