marketing-shibata50/garc-gws-agent-runtime
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: clarify prerequisites, known limitations, and roadmap for v0.1.0

Browse source 
Added explicit prerequisites section to README and quickstart,
known limitations table with planned versions, and v0.2/v0.3/v0.4
roadmap. CHANGELOG restructured with Keep a Changelog format.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
林 駿甫 (Shunsuke Hayashi) 2026-04-15 09:06:30 +09:00
parent a69b9d9160
commit 931384d671
3 changed files with 274 additions and 100 deletions
Download patch file Download diff file Expand all files Collapse all files

95
CHANGELOG.md
View file

@ -1,30 +1,89 @@
# GARC Changelog
## [0.1.0] — 2026-04-15
All notable changes to this project are documented here.
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
---
## [0.1.0] — 2026-04-15 — Initial Release
This is the first public release of GARC. Core operations for Gmail, Calendar,
Drive, Sheets, Tasks, and People are functional end-to-end. Several enterprise
features are deferred to v0.2 (see Known Limitations in README).
### Added
- `bin/garc` — Main CLI entrypoint with full command dispatch
- `lib/bootstrap.sh` — Disclosure chain loading from Google Drive (SOUL/USER/MEMORY/RULES/HEARTBEAT)
- `lib/auth.sh` — OAuth scope inference and authorization flow
- `lib/memory.sh` — Google Sheets memory sync (pull/push/search)
- `lib/send.sh` — Gmail and Google Chat message sending
- `lib/agent.sh` — Agent registry via Google Sheets
- `lib/task.sh` — Google Tasks operations (list/create/done)
- `lib/approve.sh` — Execution gate and approval flow
**CLI entrypoint**
- `bin/garc` — Main CLI with full command dispatch (gmail / calendar / drive / sheets / task / people / memory / ingress / daemon / agent / approve / auth / bootstrap / setup / status / heartbeat)
**Google Workspace operations**
- `lib/gmail.sh` + `scripts/garc-gmail-helper.py` — send / reply / search / read / inbox / draft / labels / profile
- `lib/calendar.sh` + `scripts/garc-calendar-helper.py` — today / week / list / create / delete / freebusy
- `lib/drive.sh` + `scripts/garc-drive-helper.py` — list / search / upload / download / create-doc / share / info
- `lib/sheets.sh` + `scripts/garc-sheets-helper.py` — info / read / append / update / search / clear
- `lib/task.sh` + `scripts/garc-tasks-helper.py` — list / create / done / show / update / delete / clear-completed / tasklists
- `lib/people.sh` + `scripts/garc-people-helper.py` — lookup / directory / list / contacts
**Agent runtime**
- `lib/bootstrap.sh` — Disclosure chain loading from Google Drive (SOUL.md → USER.md → MEMORY.md → RULES.md → HEARTBEAT.md)
- `lib/memory.sh` — Google Sheets memory sync (pull / push / search)
- `lib/agent.sh` — Agent registry via Google Sheets (list / register / show)
- `lib/approve.sh` — Execution gate and approval flow (gate / list / act / create)
- `lib/heartbeat.sh` — System state logging to Google Sheets
- `lib/ingress.sh` — Queue/ingress system with JSONL local cache (enqueue / list / run-once / done / fail / stats)
- `lib/daemon.sh` — Gmail polling daemon with macOS launchd support (start / stop / status / poll-once / install)
- `lib/kg.sh` — Knowledge graph via Google Drive Docs
- `lib/ingress.sh` — Queue/ingress system with JSONL local cache
**Auth & config**
- `scripts/garc-auth-helper.py` — OAuth2 scope inference + token management
- `scripts/garc-sheets-helper.py` — Google Sheets CRUD operations
- `scripts/garc-drive-helper.py` — Google Drive file operations + KG builder
- `scripts/garc-gmail-helper.py` — Gmail send operations
- `scripts/garc-tasks-helper.py` — Google Tasks operations
- `scripts/setup-workspace.sh` — One-shot workspace provisioning
- `config/scope-map.json` — 25 task types × Google OAuth scopes × 4 profiles
- `config/gate-policy.json` — Execution gate policies (none/preview/approval)
- `scripts/garc-core.py` — Shared auth, retry, and utilities
- `scripts/garc-setup.py` — One-shot workspace provisioner (garc setup all)
- `config/scope-map.json` — 42 task types × Google OAuth scopes × keyword patterns
- `config/gate-policy.json` — Execution gate policies (none / preview / approval)
- `config/config.env.example` — Configuration template
- `agents.yaml` — Default agent declarations (main/crm-agent/doc-agent/expense-processor)
- `agents.yaml` — Default agent declarations (main / crm-agent / doc-agent / expense-processor)
**Claude Code bridge**
- `scripts/garc-ingress-helper.py` — Task type inference + Claude Code execution prompt builder
- `.claude/skills/garc-runtime/SKILL.md` — Claude Code skill definition
**Documentation**
- `README.md` — Quickstart, usage, prerequisites, known limitations, roadmap
- `README.ja.md` — Japanese translation
- `docs/quickstart.md` — 15-minute setup guide
- `docs/google-cloud-setup.md` — Google Cloud Console step-by-step
- `docs/garc-architecture.md` — Full architecture reference
- `docs/garc-vs-larc.md` — GARC vs LARC comparison
- `docs/gws-api-alignment.md` — GWS API command mappings
### Known Limitations (v0.1.0)
- Google Chat integration not implemented — Gmail used as fallback for notifications
- Service Account / Domain-wide Delegation not supported — user OAuth only
- No audit log
- `garc auth revoke` not implemented
- Editing existing Google Docs body not implemented
- Google Forms → auto-enqueue pipeline not implemented
- macOS only for daemon install (launchd); Linux systemd not yet supported
- Single Google Workspace organization only
---
## Unreleased
### v0.2 — Enterprise hardening (planned)
- Google Chat API (`garc chat send`)
- Service Account + Domain-wide Delegation (`garc auth login --service-account`)
- Audit log (`garc audit log`)
- `garc auth revoke`
### v0.3 — Workflow expansion (planned)
- Google Docs body editing
- Google Forms → ingress pipeline
- Linux systemd daemon support
- GCP Secret Manager integration
### v0.4 — Multi-agent (planned)
- Cross-agent task delegation
- Agent-to-agent approval chains
- Multi-organization support

154
README.md
View file

@ -12,16 +12,59 @@ You / Claude Code
Google Workspace APIs (Gmail · Calendar · Drive · Sheets · Tasks · People)
```
## Core concepts
> **This is an initial release (v0.1.0).** Core operations work end-to-end.
> Known limitations and planned improvements are listed in [Known Limitations](#known-limitations) below.
| Concept | What it does |
|---------|-------------|
| **`auth suggest`** | Infers minimum OAuth scopes from a natural-language task description |
| **Execution gates** | `none` (read-only) / `preview` (writes, confirm first) / `approval` (financial/irreversible, requires human sign-off) |
| **Disclosure chain** | `SOUL.md → USER.md → MEMORY.md → RULES.md → HEARTBEAT.md` stored in Google Drive, loaded on bootstrap |
| **Queue / ingress** | Task lifecycle (`pending → in_progress → done/failed`), Gmail polling daemon auto-enqueues new emails |
| **Agent registry** | Agent declarations (id, model, scopes) stored in Google Sheets |
| **Memory sync** | Long-term memory round-trip with a dedicated Google Sheets tab |
---
## Prerequisites
> **Complete all steps below before running any `garc` command.**
> Skipping any step will result in authentication or API errors.
### 1. Google Account
A Google account with **Gmail, Drive, Sheets, Calendar, and Tasks** active.
- Personal Gmail accounts work for development and testing.
- Google Workspace (business) accounts work and are the primary target use case.
### 2. Python 3.10+
```bash
python3 --version # must be 3.10 or higher
```
### 3. Google Cloud Project with APIs enabled
You need a Google Cloud project with the following APIs enabled:
| API | Service name | Used for |
|-----|-------------|----------|
| Google Drive API | `drive.googleapis.com` | File storage, disclosure chain |
| Google Sheets API | `sheets.googleapis.com` | Memory, queue, agent registry |
| Gmail API | `gmail.googleapis.com` | Email send/receive/search |
| Google Calendar API | `calendar-json.googleapis.com` | Event management |
| Google Tasks API | `tasks.googleapis.com` | Task management |
| Google Docs API | `docs.googleapis.com` | Document creation |
| Google People API | `people.googleapis.com` | Contacts, directory search |
Step-by-step setup: [`docs/google-cloud-setup.md`](docs/google-cloud-setup.md)
### 4. OAuth 2.0 Credentials file
1. In [Google Cloud Console](https://console.cloud.google.com/) → **Credentials** → **Create OAuth 2.0 Client ID**
2. Application type: **Desktop app**
3. Download JSON → save as **`~/.garc/credentials.json`**
```bash
mkdir -p ~/.garc
mv ~/Downloads/client_secret_*.json ~/.garc/credentials.json
```
> Without `~/.garc/credentials.json`, all `garc` commands will fail with
> `FileNotFoundError: credentials.json not found`.
---
## Quickstart
@ -36,49 +79,34 @@ source ~/.zshrc
garc --version # → garc 0.1.0
```
### 2. Enable Google Cloud APIs
In [Google Cloud Console](https://console.cloud.google.com/), enable:
| API | Service name |
|-----|-------------|
| Google Drive API | `drive.googleapis.com` |
| Google Sheets API | `sheets.googleapis.com` |
| Gmail API | `gmail.googleapis.com` |
| Google Calendar API | `calendar-json.googleapis.com` |
| Google Tasks API | `tasks.googleapis.com` |
| Google Docs API | `docs.googleapis.com` |
| Google People API | `people.googleapis.com` |
Create an **OAuth 2.0 Client ID** (Desktop app) → download JSON → save as `~/.garc/credentials.json`.
See [`docs/google-cloud-setup.md`](docs/google-cloud-setup.md) for step-by-step instructions.
### 3. Authenticate
### 2. Authenticate
```bash
garc auth login --profile backoffice_agent
# Opens browser → Google login → authorize all scopes
# Writes ~/.garc/token.json
garc auth status
```
### 4. Provision workspace
### 3. Provision workspace
```bash
garc setup all
# Creates GARC Workspace folder in Google Drive
# Creates Google Sheets with all tabs (memory/agents/queue/heartbeat/approval/…)
# Uploads disclosure chain templates to Drive
# Writes IDs to ~/.garc/config.env
# Creates Google Sheets with all tabs (memory/agents/queue/heartbeat/approval)
# Uploads disclosure chain templates (SOUL.md / USER.md / MEMORY.md / RULES.md)
# Writes folder/sheet IDs to ~/.garc/config.env
```
### 5. Verify
### 4. Verify
```bash
garc status
garc bootstrap --agent main
```
---
## Usage
### Gmail
@ -88,6 +116,7 @@ garc gmail inbox --unread
garc gmail search "from:alice@co.com subject:invoice" --max 10
garc gmail send --to boss@co.com --subject "Weekly report" --body "..."
garc gmail read <message_id>
garc gmail draft --to boss@co.com --subject "Draft" --body "..."
```
### Google Calendar
@ -124,10 +153,19 @@ garc sheets append --sheet memory --values '["main","2026-04-20","key decision",
```bash
garc task list
garc task create "Write Q1 report" --due 2026-04-30
garc task done <task_id>
garc people lookup "Alice Smith"
garc people directory "engineering"
```
### Memory sync
```bash
garc memory pull # Download from Google Sheets
garc memory push "note text" # Append to memory tab
garc memory search "keyword"
```
### Queue / Ingress (Claude Code bridge)
```bash
@ -164,13 +202,15 @@ garc approve list
garc approve act <id> --action approve
```
---
## Architecture
```
~/.garc/
credentials.json # OAuth client credentials (Google Cloud Console)
token.json # OAuth user token (garc auth login)
config.env # GARC_DRIVE_FOLDER_ID, GARC_SHEETS_ID, …
credentials.json # OAuth client credentials (Google Cloud Console) ← YOU PROVIDE THIS
token.json # OAuth user token (garc auth login generates this)
config.env # GARC_DRIVE_FOLDER_ID, GARC_SHEETS_ID, … (garc setup all generates this)
cache/
workspace/<agent>/
SOUL.md / USER.md / MEMORY.md / RULES.md / HEARTBEAT.md
@ -188,6 +228,46 @@ garc approve act <id> --action approve
| `preview` | Medium — external writes | Show plan, confirm first |
| `approval` | High — financial / irreversible | Create approval request, block until approved |
---
## Known Limitations
The following are known gaps in v0.1.0. They are planned for future releases.
| Limitation | Impact | Planned |
|-----------|--------|---------|
| **Google Chat not implemented** | No push notifications to Chat spaces. Gmail is used as fallback for approval notifications | v0.2 |
| **Service Account / Domain-wide Delegation not supported** | Enterprise deployments requiring headless bot identity (not user OAuth) are not yet supported | v0.2 |
| **No audit log** | Operations are not logged to Admin SDK / Google Cloud Logging | v0.2 |
| **`garc auth revoke` not implemented** | Token revocation requires manual deletion of `~/.garc/token.json` | v0.2 |
| **Existing Google Docs editing limited** | `drive create-doc` creates new docs; editing body of existing Docs is not implemented | v0.3 |
| **Google Forms → auto-enqueue not implemented** | Form submissions cannot automatically create queue tasks | v0.3 |
| **Single organization only** | Multi-tenant (multiple Google Workspace domains) is not supported | v0.3+ |
| **macOS only (daemon)** | `daemon install` generates a macOS launchd plist. Linux systemd not yet supported | v0.3 |
---
## Roadmap
### v0.2 — Enterprise hardening
- Google Chat API integration (`garc chat send`)
- Service Account support (`garc auth login --service-account`)
- Audit log (`garc audit log`)
- `garc auth revoke`
### v0.3 — Workflow expansion
- Google Docs body editing
- Google Forms → ingress pipeline
- Linux systemd daemon support
- GCP Secret Manager for credentials
### v0.4 — Multi-agent
- Cross-agent task delegation
- Agent-to-agent approval chains
- Multi-organization support
---
## Repository layout
```
@ -214,6 +294,8 @@ docs/
.claude/skills/garc-runtime/SKILL.md Claude Code skill
```
---
## Relation to LARC
GARC mirrors [LARC](https://github.com/miyabi-lab/larc-openclaw-coding-agent) — the same governance model running on Google Workspace instead of Lark/Feishu.

125
docs/quickstart.md
View file

@ -1,10 +1,45 @@
# GARC Quickstart — 15分で動かす
## 前提
## このドキュメントについて
- Python 3.10+
- pip3
- Google アカウント（Gmail / Drive 使用中）
このガイドは GARC v0.1.0 の初期リリース向けです。
**以下の前提条件を全て満たしてから**進めてください。途中でスキップすると認証エラーになります。
---
## 前提条件チェックリスト
すべてに ✅ が付いてから先に進んでください。
- [ ] Python 3.10 以上がインストールされている (`python3 --version`)
- [ ] Google アカウントを持っている（Gmail / Drive が使える状態）
- [ ] Google Cloud Console でプロジェクトを作成済み
- [ ] 下記7つのAPIを有効化済み（[詳細手順](google-cloud-setup.md)）
- [ ] OAuth 2.0 クライアント ID を作成し `~/.garc/credentials.json` に保存済み
### 必須 API（7種）
| API | サービス名 |
|-----|---------|
| Google Drive API | `drive.googleapis.com` |
| Google Sheets API | `sheets.googleapis.com` |
| Gmail API | `gmail.googleapis.com` |
| Google Calendar API | `calendar-json.googleapis.com` |
| Google Tasks API | `tasks.googleapis.com` |
| Google Docs API | `docs.googleapis.com` |
| Google People API | `people.googleapis.com` |
> **APIを有効化しないと** `googleapiclient.errors.HttpError: 403 API not enabled` が出ます。
> 有効化の詳細手順: [google-cloud-setup.md](google-cloud-setup.md)
### credentials.json の配置
```bash
mkdir -p ~/.garc
# Google Cloud Console からダウンロードした JSON を配置
mv ~/Downloads/client_secret_*.json ~/.garc/credentials.json
ls ~/.garc/credentials.json # ← このファイルがないと全コマンドが失敗します
```
---
@ -28,56 +63,42 @@ garc --version
---
## Step 2 — Google Cloud Console でAPIを有効化
1. https://console.cloud.google.com/ にアクセス
2. 新規プロジェクトを作成（または既存を選択）
3. **「APIとサービス」→「APIとサービスを有効化」** で以下を有効化：
| API | サービス名 |
|-----|---------|
| Google Drive API | `drive.googleapis.com` |
| Google Sheets API | `sheets.googleapis.com` |
| Gmail API | `gmail.googleapis.com` |
| Google Calendar API | `calendar-json.googleapis.com` |
| Google Tasks API | `tasks.googleapis.com` |
| Google Docs API | `docs.googleapis.com` |
| Google People API | `people.googleapis.com` |
4. **「認証情報」→「OAuth 2.0 クライアントID」** を作成
- アプリタイプ: **デスクトップアプリ**
- JSONダウンロード → `~/.garc/credentials.json` に保存
5. **「OAuth同意画面」** → テストユーザーに自分のGmailを追加
---
## Step 3 — 認証
## Step 2 — 認証
```bash
garc auth login --profile backoffice_agent
# → ブラウザが開く → Googleログイン → 全スコープを承認
# → ~/.garc/token.json が生成される
# → ~/.garc/token.json が生成される（以降は自動更新）
garc auth status
# → 付与されたスコープが表示される
# → 付与されたスコープ一覧が表示される
```
> **よくあるエラー**
> - `credentials.json not found` → Step 0 の前提条件に戻ってください
> - `Access blocked: This app's request is invalid` → OAuth同意画面でテストユーザーに自分のGmailを追加してください
---
## Step 4 — ワークスペースを自動プロビジョニング
## Step 3 — ワークスペースを自動プロビジョニング
```bash
garc setup all
# → Google DriveにGARC Workspaceフォルダを作成
# → Google Sheetsにすべてのタブを作成（memory/agents/queue/heartbeat/approval...）
# → 開示チェーンテンプレート（SOUL.md等）をDriveにアップロード
# → ~/.garc/config.env にIDを自動保存
```
このコマンドが実行すること:
| 処理 | 結果 |
|------|------|
| Google Drive に `GARC Workspace` フォルダ作成 | `~/.garc/config.env` に `GARC_DRIVE_FOLDER_ID` が書き込まれる |
| Google Sheets に全タブ作成 | memory / agents / queue / heartbeat / approval タブが作成される |
| 開示チェーンテンプレートをアップロード | SOUL.md / USER.md / MEMORY.md / RULES.md / HEARTBEAT.md が Drive に配置される |
> **所要時間**: 初回は Google API のプロビジョニングで 1〜2 分かかります。
---
## Step 5 — 動作確認
## Step 4 — 動作確認
```bash
garc status
@ -85,10 +106,10 @@ garc status
garc bootstrap --agent main
# → DriveからSOUL.md/USER.md/MEMORY.md等を読み込み
# → ~/.garc/cache/workspace/main/AGENT_CONTEXT.md に統合
# → ~/.garc/cache/workspace/main/AGENT_CONTEXT.md に統合コンテキストを出力
garc auth suggest "send weekly report to manager"
# → スコープ推定が動く
# → gate: preview scopes: gmail.send
```
---
@ -155,10 +176,22 @@ GARC_DEFAULT_AGENT=main
## トラブルシューティング
| エラー | 対処 |
|--------|------|
| `credentials.json not found` | Google Cloud ConsoleでOAuth認証情報をダウンロード |
| `Token refresh failed` | `garc auth login` で再認証 |
| `API not enabled` | Google Cloud ConsoleでAPIを有効化 |
| `403 insufficientPermissions` | `garc auth login --profile backoffice_agent` で再認証（スコープ追加） |
| `Sheets tab missing` | `garc setup sheets` でタブを再作成 |
| エラー | 原因 | 対処 |
|--------|------|------|
| `credentials.json not found` | 認証情報ファイルが未配置 | Google Cloud ConsoleでOAuth認証情報をダウンロードし `~/.garc/credentials.json` に保存 |
| `Token refresh failed` | トークン期限切れ | `garc auth login` で再認証 |
| `403 API not enabled` | APIが有効化されていない | Google Cloud ConsoleでAPIを有効化（[手順](google-cloud-setup.md)） |
| `403 insufficientPermissions` | スコープが不足 | `garc auth login --profile backoffice_agent` で再認証（全スコープを付与） |
| `Sheets tab missing` | Sheetsが未作成 | `garc setup sheets` でタブを再作成 |
| `Access blocked` | テストユーザー未登録 | OAuth同意画面でテストユーザーにGmailを追加 |
---
## v0.1.0 の既知制限
このリリースで未実装の機能です。詳細は [README の Known Limitations](../README.md#known-limitations) を参照してください。
- Google Chat 通知 → Gmail で代替
- Service Account（ヘッドレス・ボット用途）→ v0.2 で対応予定
- 監査ログ → v0.2 で対応予定
- `garc auth revoke` → 手動で `~/.garc/token.json` を削除してください