@geekbeer/minion 2.10.3 → 2.11.1

package/{rules/minion.md → docs/api-reference.md}

@@ -1,67 +1,9 @@
-# Minion Agent Environment
+# Minion API Reference
 
-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.
+このドキュメントはミニオンが利用可能なAPIの全仕様です。
+HQのソースコードを読む必要はありません — 必要な情報はすべてここに記載されています。
 
-## Architecture: Project / Workflow / Routine
-
-```
-Project (組織・課金単位)
-├── Context (markdown, PMが更新)
-├── Members (minion + role: pm | engineer)
-└── Workflows (何をするか + オプションのcronスケジュール)
-    ├── Versions (pipeline の不変スナップショット)
-    └── Executions (実行履歴, ステップごとの進捗)
-
-Minion
-└── Routines (いつ・何を, cron付き, ミニオンローカルのタスク)
-```
-
-- **Workflow** はプロジェクトスコープ。バージョン管理されたパイプライン（スキル列）を持つ。オプションで `cron_expression` によるスケジュール実行が可能。HQ UIからワンショット実行もできる。
-- **Routine** はミニオンスコープ。ミニオンローカルの定期タスク。cron_expression を持ち自律トリガーする。
-- ミニオンは複数プロジェクトに `pm` または `engineer` として参加できる。
-- ワークフローの各ステップには `assigned_role`（pm/engineer）と `requires_review` フラグがある。
-
-## Workflow Execution Model (DB ステートマシン)
-
-ワークフロー実行はHQのDBがステートマシンとして管理する。ミニオン間通信は不要。
-
-```
-1. Execution 作成 (HQ UIのRunボタン or cronスケジュール)
-   → workflow_execution (status='pending')
-   → workflow_step_executions (全ステップ status='pending')
-
-2. ミニオンエージェントが GET /api/minion/pending-steps をポーリング
-   → 自分のロールに該当 & 前ステップ完了済みのステップを取得
-
-3. ミニオンがステップを実行し完了を報告
-   → POST /api/minion/execution で status/outcome を更新
-
-4. 次ステップが eligible に → 別のミニオンが検知して実行
-   → requires_review=true の場合はHQでレビュー承認後に次へ
-
-5. 全ステップ完了 → execution 全体を completed に
-```
-
-**ポイント:**
-- HQの責務は「executionレコードを作る（指示書発行）」だけ
-- 各ミニオンは自分の担当ステップだけをポーリングして実行
-- ミニオンエージェント（Port 3001）が軽量HTTPポーリングを行い、pending検知時のみClaude Codeを起動（トークン節約）
-
-## CLI Commands
-
-```bash
-minion-cli status                         # Get current status (online/offline/busy)
-minion-cli health                         # Health check
-minion-cli set-status <status> [task]     # Set status and optional task description
-minion-cli skill push <name>              # Push local skill to HQ
-minion-cli skill fetch <name>             # Fetch skill from HQ to local
-minion-cli skill list                     # List skills on HQ
-minion-cli skill list --local             # List local deployed skills
-minion-cli --version                      # Show package version
-# Service management (requires sudo):
-# sudo minion-cli start | stop | restart
-```
+---
 
 ## Agent API Endpoints (http://localhost:3001)
 
@@ -142,6 +84,8 @@ Files are stored in `~/files/`. Max upload size: 50MB.
 
 Available commands: `restart-agent`, `update-agent`, `restart-display`, `status-services`
 
+---
+
 ## HQ API Endpoints (https://<HQ_URL>)
 
 Authentication: `Authorization: Bearer $API_TOKEN` header.
@@ -230,6 +174,60 @@ POST body (push):
 
 push するとパイプライン内のスキル名が `skill_version_id` に解決され、新バージョンが自動作成される。
 
+### Workflow Structure
+
+```json
+{
+  "name": "my-workflow",
+  "pipeline_skill_names": ["skill-1", "skill-2", "execution-report"],
+  "pipeline": [
+    {
+      "skill_version_id": "uuid",
+      "skill_name": "skill-1",
+      "skill_display_name": "Skill One",
+      "skill_version": 2,
+      "assigned_role": "engineer",
+      "requires_review": false,
+      "is_my_step": true
+    }
+  ],
+  "content": "Markdown description of the workflow",
+  "version": 2,
+  "cron_expression": "0 9 * * *",
+  "project_id": "uuid"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Slug identifier (`/^[a-z0-9-]+$/`) |
+| `pipeline_skill_names` | string[] | Ordered skill names (for display/push) |
+| `pipeline` | PipelineStep[] | Resolved pipeline with version IDs and roles |
+| `content` | string | Markdown body describing the workflow |
+| `version` | number | Current version number (auto-incremented on push) |
+| `cron_expression` | string\|null | Cron schedule (null = manual/one-shot only) |
+| `project_id` | string | UUID of the parent project |
+
+### Pipeline Step Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `skill_version_id` | string | UUID of the specific skill version |
+| `skill_name` | string | Skill slug name |
+| `skill_display_name` | string | Human-readable skill name |
+| `skill_version` | number | Skill version number |
+| `assigned_role` | string | `"pm"` or `"engineer"` — who executes this step |
+| `requires_review` | boolean | If true, human review required after completion |
+| `is_my_step` | boolean | Whether this minion's role matches assigned_role |
+
+### Syncing Workflows with HQ
+
+- `POST /api/workflows/push/:name` — Push local workflow to HQ. Pipeline skills are auto-pushed first.
+- `POST /api/workflows/fetch/:name` — Fetch workflow from HQ. Missing pipeline skills are auto-fetched.
+- `GET /api/workflows/remote` — List workflows available on HQ.
+
+Pipeline skills must be deployed locally (in `~/.claude/skills/`) before pushing a workflow.
+
 ### Pending Steps (軽量ポーリング)
 
 | Method | Endpoint | Description |
@@ -237,7 +235,6 @@ push するとパイプライン内のスキル名が `skill_version_id` に解
 | GET | `/api/minion/pending-steps` | 自分が実行すべき pending ステップ一覧 |
 
 **このエンドポイントはミニオンエージェント（非AI）による高頻度ポーリング用。**
-Claude Code（AIスキル実行）はステップ検知時のみ起動する。
 
 Response:
 ```json
@@ -329,7 +326,7 @@ Response:
 
 使用可能なラベル: `bug`, `enhancement`, `critical`, `minor`
 
-**使い方:** サービスのバグや改善点を発見したら、このエンドポイントで GitHub Issue を起票する。報告者のミニオン名と ID が自動で本文に付記される。
+報告者のミニオン名と ID が自動で本文に付記される。
 
 ### Routines (minion-scoped)
 
@@ -355,127 +352,7 @@ Response:
 ]
 ```
 
-### Skills
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| GET | `/api/minion/skills` | HQ に登録されたスキル一覧 |
-| GET | `/api/minion/skills/[name]` | スキル詳細取得（content, files 含む） |
-| POST | `/api/minion/skills` | スキル登録/更新（新バージョン自動作成） |
-
-スキルはバージョン管理される。push ごとに新バージョンが作成され、ファイルは Supabase Storage に保存される。
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `HQ_URL` | HQ server URL (empty = standalone mode) |
-| `API_TOKEN` | Bearer token for HQ and local API auth |
-| `MINION_ID` | UUID assigned by HQ |
-| `AGENT_PORT` | Agent HTTP port (default: 3001) |
-| `MINION_USER` | System user running the agent |
-
-## Skills Directory Structure
-
-Skills are stored in `~/.claude/skills/<name>/`:
-
-```
-~/.claude/skills/<name>/
-  SKILL.md          # Skill definition (YAML frontmatter + markdown body)
-  references/       # Optional supporting files
-```
-
-SKILL.md format:
-```markdown
----
-name: my-skill
-description: What this skill does
----
-
-Skill instructions here...
-```
-
-## HQ Connection
-
-When `HQ_URL` and `API_TOKEN` are set, the agent sends heartbeats and syncs with HQ.
-Use `minion-cli skill push/fetch` to sync skills between local and HQ.
-Use the workflow API endpoints (`/api/workflows/push/:name`, `/api/workflows/fetch/:name`) to sync workflows.
-When not configured, the agent runs in standalone mode and HQ-dependent features return errors.
-
-## Workflow Structure
-
-Workflows are project-scoped and versioned. Each version is an immutable snapshot of the pipeline.
-Fetched from HQ via `GET /api/minion/workflows`. Also stored locally in `workflows.json`.
-
-```json
-{
-  "name": "my-workflow",
-  "pipeline_skill_names": ["skill-1", "skill-2", "execution-report"],
-  "pipeline": [
-    {
-      "skill_version_id": "uuid",
-      "skill_name": "skill-1",
-      "skill_display_name": "Skill One",
-      "skill_version": 2,
-      "assigned_role": "engineer",
-      "requires_review": false,
-      "is_my_step": true
-    }
-  ],
-  "content": "Markdown description of the workflow",
-  "version": 2,
-  "cron_expression": "0 9 * * *",
-  "project_id": "uuid"
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | string | Slug identifier (`/^[a-z0-9-]+$/`) |
-| `pipeline_skill_names` | string[] | Ordered skill names (for display/push) |
-| `pipeline` | PipelineStep[] | Resolved pipeline with version IDs and roles |
-| `content` | string | Markdown body describing the workflow |
-| `version` | number | Current version number (auto-incremented on push) |
-| `cron_expression` | string\|null | Cron schedule (null = manual/one-shot only) |
-| `project_id` | string | UUID of the parent project |
-
-### Pipeline Step Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `skill_version_id` | string | UUID of the specific skill version |
-| `skill_name` | string | Skill slug name |
-| `skill_display_name` | string | Human-readable skill name |
-| `skill_version` | number | Skill version number |
-| `assigned_role` | string | `"pm"` or `"engineer"` — who executes this step |
-| `requires_review` | boolean | If true, human review required after completion |
-| `is_my_step` | boolean | Whether this minion's role matches assigned_role |
-
-### Syncing workflows with HQ
-
-- `POST /api/workflows/push/:name` — Push local workflow to HQ. Pipeline skills are auto-pushed first.
-- `POST /api/workflows/fetch/:name` — Fetch workflow from HQ. Missing pipeline skills are auto-fetched.
-- `GET /api/workflows/remote` — List workflows available on HQ.
-
-Pipeline skills must be deployed locally (in `~/.claude/skills/`) before pushing a workflow.
-
-## Routine Structure
-
-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"
-}
-```
+### Routine Structure
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -488,44 +365,12 @@ They are also stored locally in `routines.json`. Each routine object:
 | `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_ROUTINE_ID`, `MINION_ROUTINE_NAME` are available during execution
-
-## Workflow Step Execution via Pending Steps
-
-ミニオンエージェントは `GET /api/minion/pending-steps` を定期ポーリングし、
-自分の担当ステップを検知したら Claude Code を起動してスキルを実行する。
-
-```
-ミニオンエージェント (Port 3001, 常駐, トークン不要)
-  │
-  ├── 軽量ポーリング: N秒ごとに GET /api/minion/pending-steps
-  │   → HTTPのみ、AIなし、コストゼロ
-  │   → pendingステップがなければ何もしない
-  │
-  └── ステップ検知時のみ:
-      1. Claude Code 起動 → 該当スキルを実行
-      2. POST /api/minion/execution → ステップ完了を報告
-      3. Claude Code 終了 → トークン消費はここだけ
-```
-
-### Workflow Execution via Routine (従来方式)
+### Skills
 
-ワークフローは `project-workflow-check` システムスキルを通じてルーティンからも実行可能:
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/minion/skills` | HQ に登録されたスキル一覧 |
+| GET | `/api/minion/skills/[name]` | スキル詳細取得（content, files 含む） |
+| POST | `/api/minion/skills` | スキル登録/更新（新バージョン自動作成） |
 
-```
-ルーティン: "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 に結果報告
-```
+スキルはバージョン管理される。push ごとに新バージョンが作成され、ファイルは Supabase Storage に保存される。

package/docs/task-guides.md

@@ -0,0 +1,217 @@
+# Minion Task Guides
+
+よくある操作の手順書です。API仕様の詳細は `~/.minion/docs/api-reference.md` を参照してください。
+
+---
+
+## スキルの修正
+
+### 1. ローカルのスキルを編集する
+
+```bash
+# スキル一覧を確認
+minion-cli skill list --local
+
+# SKILL.md を編集
+vi ~/.claude/skills/<name>/SKILL.md
+```
+
+SKILL.md フォーマット:
+```markdown
+---
+name: my-skill
+display_name: My Skill
+description: What this skill does
+---
+
+Skill instructions here...
+```
+
+### 2. HQ に反映する
+
+```bash
+minion-cli skill push <name>
+```
+
+push するとHQ上で新バージョンが自動作成されます。
+
+### 3. HQ からスキルを取得する
+
+```bash
+# HQ上のスキル一覧
+minion-cli skill list
+
+# 特定のスキルをローカルにデプロイ
+minion-cli skill fetch <name>
+```
+
+---
+
+## ワークフローの修正 (PM のみ)
+
+### パイプライン構成の変更
+
+```bash
+# API経由で push (新バージョン自動作成)
+curl -s -X POST "$HQ_URL/api/minion/workflows" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-workflow",
+    "pipeline_skill_names": ["skill-1", "skill-2"],
+    "content": "Workflow description",
+    "project_id": "<project-uuid>",
+    "change_summary": "Updated pipeline"
+  }'
+```
+
+### ステップごとのロール・レビュー設定
+
+```bash
+curl -s -X POST "$HQ_URL/api/minion/workflows" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my-workflow",
+    "pipeline_skill_names": ["skill-1", "skill-2"],
+    "pipeline_steps": [
+      { "assigned_role": "engineer", "requires_review": false },
+      { "assigned_role": "pm", "requires_review": true }
+    ],
+    "content": "Workflow description",
+    "project_id": "<project-uuid>"
+  }'
+```
+
+### ローカルワークフローの同期
+
+```bash
+# HQからワークフローを取得 (不足スキルも自動fetch)
+curl -s -X POST "http://localhost:3001/api/workflows/fetch/<name>" \
+  -H "Authorization: Bearer $API_TOKEN"
+
+# ローカルワークフローをHQにpush (スキルも自動push)
+curl -s -X POST "http://localhost:3001/api/workflows/push/<name>" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+---
+
+## プロジェクトコンテキストの操作
+
+### 取得
+
+```bash
+# プロジェクト一覧を取得
+curl -s "$HQ_URL/api/minion/me/projects" \
+  -H "Authorization: Bearer $API_TOKEN"
+
+# コンテキストを取得
+curl -s "$HQ_URL/api/minion/me/project/<project-id>/context" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+### 更新 (PM のみ)
+
+```bash
+curl -s -X PUT "$HQ_URL/api/minion/me/project/<project-id>/context" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "content": "Updated context markdown" }'
+```
+
+---
+
+## 実行結果の確認
+
+### ローカル実行履歴
+
+```bash
+# 最近の実行一覧
+curl -s "http://localhost:3001/api/executions?limit=10" \
+  -H "Authorization: Bearer $API_TOKEN"
+
+# 特定の実行ログ
+curl -s "http://localhost:3001/api/executions/<id>/log" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+### 実行結果の報告
+
+```bash
+curl -s -X POST "http://localhost:3001/api/executions/<id>/outcome" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "outcome": "success",
+    "summary": "Brief summary",
+    "details": "## Detailed Report\n\n- Action 1\n- Action 2"
+  }'
+```
+
+outcome values: `success`, `failure`, `partial`
+
+---
+
+## GitHub Issue の起票
+
+バグや改善点を発見した場合:
+
+```bash
+curl -s -X POST "$HQ_URL/api/minion/report" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Issue title",
+    "body": "## 状況\n...\n\n## 再現手順\n...",
+    "labels": ["bug"]
+  }'
+```
+
+使用可能なラベル: `bug`, `enhancement`, `critical`, `minor`
+
+Node.js API も利用可能:
+
+```javascript
+const { reportIssue } = require('@geekbeer/minion/api')
+await reportIssue({ title: '...', body: '...', labels: ['bug'] })
+```
+
+---
+
+## トラブルシューティング
+
+### HQ APIの仕様がわからない
+
+`~/.minion/docs/api-reference.md` に全エンドポイントの仕様が記載されています。
+**HQのソースコードを読みに行く必要はありません。**
+
+### スキルが見つからない
+
+```bash
+# ローカルスキル一覧
+minion-cli skill list --local
+
+# HQから再取得
+minion-cli skill fetch <name>
+```
+
+### ワークフローが実行されない
+
+```bash
+# ローカルワークフロー一覧 (next_run を確認)
+curl -s "http://localhost:3001/api/workflows" \
+  -H "Authorization: Bearer $API_TOKEN"
+
+# 手動トリガー
+curl -s -X POST "http://localhost:3001/api/workflows/trigger" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "workflow_id": "<workflow-uuid>" }'
+```
+
+### エージェントの状態確認
+
+```bash
+minion-cli health
+minion-cli status
+```

package/minion-cli.sh

@@ -628,8 +628,13 @@ SUPEOF
 
   if [ -d "$BUNDLED_RULES_DIR" ]; then
     $RUN_AS mkdir -p "$CLAUDE_RULES_DIR"
-    $RUN_AS cp "$BUNDLED_RULES_DIR"/minion.md "$CLAUDE_RULES_DIR"/minion.md
-    echo "  -> Deployed Claude rules: minion.md"
+    $RUN_AS cp "$BUNDLED_RULES_DIR"/core.md "$CLAUDE_RULES_DIR"/core.md
+    echo "  -> Deployed Claude rules: core.md"
+    # Remove legacy minion.md if present
+    if [ -f "$CLAUDE_RULES_DIR/minion.md" ]; then
+      $RUN_AS rm -f "$CLAUDE_RULES_DIR/minion.md"
+      echo "  -> Removed legacy rules: minion.md"
+    fi
   fi
 
   # Step 10 (optional): Cloudflare Tunnel setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "2.10.3",
+  "version": "2.11.1",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "server.js",
   "bin": {
@@ -20,6 +20,8 @@
     "routes/",
     "skills/",
     "rules/",
+    "roles/",
+    "docs/",
     "settings/",
     "minion-cli.sh",
     ".env.example"

package/roles/engineer.md

@@ -0,0 +1,31 @@
+# Engineer Role Guidelines
+
+このセッションではあなたは **Engineer** ロールとして行動します。
+
+## 責務
+
+- **スキル実行**: 割り当てられたワークフローステップ（スキル）を確実に実行する
+- **タスク完了**: スキルの指示に従い、成果物を生成する
+- **結果報告**: 実行結果を `/execution-report` または API 経由で報告する
+
+## 重要なルール
+
+- **ワークフローの構造変更（パイプライン構成、ステップ追加/削除）はPMの責任です。** 自分では変更しないでください。
+- 割り当てられたスキルの実行に集中してください。
+- スキルの内容（SKILL.md）の修正は可能です。修正後は `minion-cli skill push <name>` でHQに反映してください。
+
+## スキル修正
+
+スキルの内容を改善する場合:
+
+1. `~/.claude/skills/<name>/SKILL.md` を編集
+2. `minion-cli skill push <name>` でHQに反映
+
+詳細な手順は `~/.minion/docs/task-guides.md` を参照。
+
+## 実行コンテキスト
+
+ワークフロー実行中は以下の環境変数が利用可能:
+- `MINION_EXECUTION_ID` — 現在の実行UUID
+- `MINION_WORKFLOW_ID` — ワークフローUUID
+- `MINION_WORKFLOW_NAME` — ワークフロー名

package/roles/pm.md

@@ -0,0 +1,58 @@
+# PM Role Guidelines
+
+このセッションではあなたは **PM (Project Manager)** ロールとして行動します。
+
+## 責務
+
+- **ワークフロー管理**: ワークフローの作成・修正・バージョン管理
+- **プロジェクトコンテキスト管理**: プロジェクトの共有コンテキスト（markdown）の更新
+- **オーケストレーション**: ワークフローステップのディスパッチ、エンジニアミニオンへの指示
+- **レビュー**: `requires_review=true` のステップの承認判断
+
+## Workflow Execution Model
+
+ワークフロー実行はHQのDBがステートマシンとして管理する。ミニオン間の直接通信は不要。
+
+```
+1. Execution 作成 → workflow_execution + 全 step_executions (status='pending')
+2. ミニオンエージェントが GET /api/minion/pending-steps をポーリング
+   → 自分のロールに該当 & 前ステップ完了済みのステップを取得
+3. ミニオンがステップを実行し完了を報告
+4. 次ステップが eligible に → 別のミニオンが検知して実行
+5. 全ステップ完了 → execution 全体を completed に
+```
+
+ポイント:
+- HQの責務は「executionレコードを作る（指示書発行）」だけ
+- 各ミニオンは自分の担当ステップだけをポーリングして実行
+- ミニオンエージェント（Port 3001）が軽量HTTPポーリングを行い、pending検知時のみClaude Codeを起動
+
+## Workflow 管理
+
+ワークフローはプロジェクトスコープ・バージョン管理される。
+
+- 作成/修正: `POST /api/minion/workflows` で push（新バージョン自動作成）
+- 各ステップに `assigned_role` (pm/engineer) と `requires_review` を設定可能
+- `is_my_step` フラグで自分の担当ステップを確認
+
+詳細な API 仕様とリクエスト/レスポンス形式は `~/.minion/docs/api-reference.md` を参照。
+ワークフロー修正の具体的な手順は `~/.minion/docs/task-guides.md` を参照。
+
+## Project Context 管理
+
+- `GET /api/minion/me/project/[id]/context` でコンテキスト取得
+- `PUT /api/minion/me/project/[id]/context` でコンテキスト更新（PMのみ）
+
+## 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 を順に実行
+```

package/routes/skills.js

@@ -288,7 +288,7 @@ async function skillRoutes(fastify) {
       return { success: false, error: 'Unauthorized' }
     }
 
-    const { skill_name, execution_id, step_index, workflow_name } = request.body || {}
+    const { skill_name, execution_id, step_index, workflow_name, role } = request.body || {}
 
     if (!skill_name) {
       reply.code(400)
@@ -335,6 +335,7 @@ async function skillRoutes(fastify) {
     // because the post-execution hook below handles completion reporting.
     const isDispatchedStep = execution_id && step_index != null
     const runOptions = isDispatchedStep ? { skipExecutionReport: true } : {}
+    if (role) runOptions.role = role
 
     // Run asynchronously — respond immediately
     const executionPromise = (async () => {

package/routine-runner.js

@@ -97,7 +97,13 @@ async function executeRoutineSession(routine, executionId, skillNames) {
 
   // Build prompt: run each skill in sequence, then execution-report
   const skillCommands = skillNames.map(name => `/${name}`).join(', then ')
-  const prompt = `Run the following skills in order: ${skillCommands}. After completing all skills, run /execution-report to report the results.`
+
+  // Inject routine context as prompt prefix (mirrors workflow-runner's role injection pattern)
+  const contextPrefix = routine.context
+    ? `## Context\n\n${routine.context}\n\n---\n\n`
+    : ''
+
+  const prompt = `${contextPrefix}Run the following skills in order: ${skillCommands}. After completing all skills, run /execution-report to report the results.`
 
   // Extend PATH to include common CLI installation locations
   const additionalPaths = [

package/routine-store.js

@@ -94,6 +94,7 @@ async function upsertFromHQ(routineData) {
       name: routineData.name,
       pipeline_skill_names: routineData.pipeline_skill_names,
       content: routineData.content || '',
+      context: routineData.context || null,
       is_active: routineData.is_active,
       cron_expression: routineData.cron_expression || '',
     }
@@ -103,6 +104,7 @@ async function upsertFromHQ(routineData) {
       name: routineData.name,
       pipeline_skill_names: routineData.pipeline_skill_names || [],
       content: routineData.content || '',
+      context: routineData.context || null,
       is_active: routineData.is_active ?? false,
       cron_expression: routineData.cron_expression || '',
       last_run: routineData.last_run || null,

package/rules/core.md

@@ -0,0 +1,94 @@
+# Minion Agent
+
+You are an AI agent running on a Minion VPS, managed by @geekbeer/minion.
+
+## Important Principles
+
+- **HQサーバーのソースコードを読みに行く必要はありません。** 必要なAPI仕様はすべてドキュメントに記載されています。
+- API の詳細仕様が必要な場合は `~/.minion/docs/api-reference.md` を参照してください。
+- タスクの手順が不明な場合は `~/.minion/docs/task-guides.md` を参照してください。
+
+## Architecture
+
+```
+Project (組織・課金単位)
+├── Context (markdown, PMが更新)
+├── Members (minion + role: pm | engineer)
+└── Workflows (スキルのパイプライン + オプションcronスケジュール)
+    ├── Versions (pipeline の不変スナップショット)
+    └── Executions (実行履歴, ステップごとの進捗)
+
+Minion
+└── Routines (ミニオンローカルの定期タスク, cron付き)
+```
+
+- **Workflow**: プロジェクトスコープ。バージョン管理されたスキルパイプライン。
+- **Routine**: ミニオンスコープ。ミニオンローカルの定期タスク。
+- ミニオンは複数プロジェクトに `pm` または `engineer` として参加できる。
+
+## Available Tools
+
+### CLI
+
+```bash
+minion-cli status                         # ステータス確認
+minion-cli health                         # ヘルスチェック
+minion-cli set-status <status> [task]     # ステータス更新
+minion-cli skill push <name>              # スキルをHQにpush
+minion-cli skill fetch <name>             # HQからスキルをfetch
+minion-cli skill list [--local]           # スキル一覧
+minion-cli --version                      # バージョン確認
+```
+
+### Local Agent API
+
+`http://localhost:3001` — 認証: `Authorization: Bearer $API_TOKEN`
+
+主なカテゴリ: Health, Skills, Workflows, Executions, Terminal, Files, Commands
+
+### HQ API
+
+`$HQ_URL/api/minion/*` — 認証: `Authorization: Bearer $API_TOKEN`
+
+主なカテゴリ: Projects, Context, Workflows, Skills, Executions, Routines, Reports
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `HQ_URL` | HQ server URL (empty = standalone mode) |
+| `API_TOKEN` | Bearer token for HQ and local API auth |
+| `MINION_ID` | UUID assigned by HQ |
+| `AGENT_PORT` | Agent HTTP port (default: 3001) |
+| `MINION_USER` | System user running the agent |
+
+Workflow/Routine 実行中は以下も利用可能:
+- `MINION_EXECUTION_ID` — 実行UUID
+- `MINION_WORKFLOW_ID` / `MINION_ROUTINE_ID` — ワークフロー/ルーティンUUID
+- `MINION_WORKFLOW_NAME` / `MINION_ROUTINE_NAME` — 名前
+
+## Skills Directory
+
+```
+~/.claude/skills/<name>/
+  SKILL.md          # スキル定義 (YAML frontmatter + markdown)
+  references/       # 参照ファイル (オプション)
+```
+
+## HQ Connection
+
+`HQ_URL` と `API_TOKEN` が設定されている場合、HQと同期。
+未設定の場合はスタンドアロンモードで動作。
+
+## Role Context
+
+ワークフロー実行時、ロールに応じたガイドラインがプロンプトで指示されます。
+ロールファイルは `~/.minion/roles/` に配置されています:
+- `pm.md` — PM (Project Manager) のガイドライン
+- `engineer.md` — Engineer のガイドライン
+
+## Documentation
+
+API仕様やタスク手順の詳細は以下を参照:
+- `~/.minion/docs/api-reference.md` — ローカルAPI・HQ APIの全エンドポイント仕様
+- `~/.minion/docs/task-guides.md` — スキル修正・ワークフロー管理等の手順書

package/server.js

@@ -103,7 +103,8 @@ function syncTmuxConfig() {
 
 /**
  * Sync bundled rules from the package to ~/.claude/rules/.
- * Runs on every server start to ensure rules stay up-to-date after package updates.
+ * Deploys core.md only. Role context is injected per-execution, not as rules.
+ * Removes legacy files (minion.md, role-*.md) if present.
  */
 function syncBundledRules() {
   const bundledRulesDir = path.join(__dirname, 'rules')
@@ -114,24 +115,90 @@ function syncBundledRules() {
 
     fs.mkdirSync(targetRulesDir, { recursive: true })
 
-    for (const file of fs.readdirSync(bundledRulesDir)) {
+    // Always deploy core.md
+    const coreSrc = path.join(bundledRulesDir, 'core.md')
+    if (fs.existsSync(coreSrc)) {
+      fs.copyFileSync(coreSrc, path.join(targetRulesDir, 'core.md'))
+      console.log('[Rules] Synced: core.md')
+    }
+
+    // Remove legacy files if present
+    for (const legacy of ['minion.md', 'role-pm.md', 'role-engineer.md']) {
+      const legacyPath = path.join(targetRulesDir, legacy)
+      if (fs.existsSync(legacyPath)) {
+        fs.unlinkSync(legacyPath)
+        console.log(`[Rules] Removed legacy: ${legacy}`)
+      }
+    }
+  } catch (err) {
+    console.error(`[Rules] Failed to sync bundled rules: ${err.message}`)
+  }
+}
+
+/**
+ * Sync bundled role context files to ~/.minion/roles/.
+ * These are NOT loaded as Claude Code rules — they are injected
+ * into the prompt at execution time based on the minion's role.
+ */
+function syncBundledRoles() {
+  const bundledRolesDir = path.join(__dirname, 'roles')
+  const targetRolesDir = path.join(config.HOME_DIR, '.minion', 'roles')
+
+  try {
+    if (!fs.existsSync(bundledRolesDir)) return
+
+    fs.mkdirSync(targetRolesDir, { recursive: true })
+
+    for (const file of fs.readdirSync(bundledRolesDir)) {
       if (!file.endsWith('.md')) continue
-      const src = path.join(bundledRulesDir, file)
-      const dest = path.join(targetRulesDir, file)
+      const src = path.join(bundledRolesDir, file)
+      const dest = path.join(targetRolesDir, file)
       fs.copyFileSync(src, dest)
-      console.log(`[Rules] Synced: ${file}`)
+      console.log(`[Roles] Synced: ${file}`)
     }
   } catch (err) {
-    console.error(`[Rules] Failed to sync bundled rules: ${err.message}`)
+    console.error(`[Roles] Failed to sync bundled roles: ${err.message}`)
+  }
+}
+
+/**
+ * Sync bundled documentation files to ~/.minion/docs/.
+ * These are reference documents accessed on-demand by Claude Code,
+ * NOT loaded automatically as rules.
+ */
+function syncBundledDocs() {
+  const bundledDocsDir = path.join(__dirname, 'docs')
+  const targetDocsDir = path.join(config.HOME_DIR, '.minion', 'docs')
+
+  try {
+    if (!fs.existsSync(bundledDocsDir)) return
+
+    fs.mkdirSync(targetDocsDir, { recursive: true })
+
+    for (const file of fs.readdirSync(bundledDocsDir)) {
+      if (!file.endsWith('.md')) continue
+      const src = path.join(bundledDocsDir, file)
+      const dest = path.join(targetDocsDir, file)
+      fs.copyFileSync(src, dest)
+      console.log(`[Docs] Synced: ${file}`)
+    }
+  } catch (err) {
+    console.error(`[Docs] Failed to sync bundled docs: ${err.message}`)
   }
 }
 
 // Start server
 async function start() {
   try {
-    // Sync bundled rules to ~/.claude/rules/ (keeps rules fresh after package updates)
+    // Sync bundled rules to ~/.claude/rules/ (core.md only)
     syncBundledRules()
 
+    // Sync bundled roles to ~/.minion/roles/ (injected per-execution)
+    syncBundledRoles()
+
+    // Sync bundled docs to ~/.minion/docs/ (on-demand reference)
+    syncBundledDocs()
+
     // Sync bundled permissions to ~/.claude/settings.json (broad allow + deny-list)
     syncPermissions()
 

package/workflow-runner.js

@@ -98,9 +98,15 @@ async function executeWorkflowSession(workflow, executionId, skillNames, options
   // When skipExecutionReport is true (dispatched step), the minion server's
   // post-execution hook handles completion reporting instead of /execution-report.
   const skillCommands = skillNames.map(name => `/${name}`).join(', then ')
+
+  // Inject role context if provided (e.g. "pm" or "engineer")
+  const rolePrefix = options.role
+    ? `You are acting as the "${options.role}" role in this session. Read ~/.minion/roles/${options.role}.md for your role guidelines before proceeding.\n\n`
+    : ''
+
   const prompt = options.skipExecutionReport
-    ? `Run the following skills in order: ${skillCommands}.`
-    : `Run the following skills in order: ${skillCommands}. After completing all skills, run /execution-report to report the results.`
+    ? `${rolePrefix}Run the following skills in order: ${skillCommands}.`
+    : `${rolePrefix}Run the following skills in order: ${skillCommands}. After completing all skills, run /execution-report to report the results.`
 
   // Extend PATH to include common CLI installation locations
   const additionalPaths = [