# AlpacaLoop

Issue tracker 上の目的を、見える形で制御できる AI coding workflow に変えます。

[English](README.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)

![AlpacaLoop workflow banner](https://unpkg.com/alpacaloop/assets/alpacaloop-readme-workflow.png)

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Status: early release](https://img.shields.io/badge/status-early_release-blue.svg)](package.json)
[![GitHub](https://img.shields.io/badge/github-alpacaloop%2Falpacaloop-24292e.svg?logo=github)](https://github.com/alpacaloop/alpacaloop)

AlpacaLoop は、AI coding worker の作業状態を一回限りの chat の外に残したいチーム向けの tool です。GitHub / Gitea / GitLab に作業を issue として書くと、AlpacaLoop は worker の plan、progress、blocker、handoff を tracker issue に紐づけたまま、Codex / Claude または OpenAI 互換 custom worker に repo-local workflow で作業させます。

AlpacaLoop は early release です。現時点で利用できますが、1.0 までは API や動作が変わる可能性があります。

## Why People Use It

AI coding は、worker が目的を覚え、状態を見せ、止まるべき時に止まれるほど扱いやすくなります。AlpacaLoop はその運用 loop に集中しています。

- チームが普段見る場所に作業を残す。目的、制約、状態、follow-up の source of truth を issue に置けます。
- AI の進捗を確認しやすくする。plan、label、managed comment、log、blocker、handoff によって run を review しやすくします。
- チームの進め方を再利用する。repository 内の workflow template で planning、implementation、pull request review、unplanned work、follow-up、improvement を導けます。
- tracker から継続的に進める。background service が ready issue を polling します。必要な場合は CLI から 1 回だけの manual run も使えます。
- 人間の制御を残す。入力、approval、不明確な判断、setup 問題が必要な場面では、勝手に推測せず停止します。

## What to Expect

AlpacaLoop は tracker-visible な状態と local worker run を管理します。code review、CI、release process を置き換えるものではありません。

- `alpaca init` は repository を 1 つ接続し、`alpaca.config.json` を書きます。
- worker sign-in は machine-local です。secret や OAuth browser login は人間が処理する handoff step のままです。
- 通常の managed issue には `AI: Ready` queue label が付き、enabled service が拾えるようになります。
- background service は、polling を止めたい場合や 1 回だけ manual cycle を実行したい場合に disable できます。
- workflow template と system prompt は、関連する local change を publish した後に background automation へ反映されます。

## Install

macOS / Linux:

```bash
curl -fsSL https://raw.githubusercontent.com/alpacaloop/alpacaloop/main/install.sh | bash
```

installer は Node.js の状態を確認し、AlpacaLoop CLI をインストールして次のセットアップ手順を表示します。AlpacaLoop は native Git を使います。不足依存を自動インストールするのは明示した場合だけです。

```bash
curl -fsSL https://raw.githubusercontent.com/alpacaloop/alpacaloop/main/install.sh | bash -s -- --install-deps
```

default の Git install には `git`、`npm`、Node.js `>=22.19.0` が必要です。`--install-deps` を付けると不足している Node.js tooling は `fnm` 経由で入りますが、`git` は事前に必要です。

Linux / WSL2 では、fnm/nvm など user-writable な npm prefix を推奨します。distro の Node.js package は `node` だけで `npm` を含まない場合があるため、その場合は `npm` も入れるか `--install-deps` で fnm-managed Node.js を使ってください。global `npm install -g` が EACCES で失敗した場合は、sudo で AlpacaLoop setup を実行せず npm prefix を直してください。

現在の npm registry beta channel は次でインストールできます。

```bash
npm install -g alpacaloop@beta
```

default の npm install は `latest` dist-tag を使うため、stable promotion までは beta channel より古い場合があります。

```bash
npm install -g alpacaloop
```

未リリースの `main` から source install する場合は Git URL を使います。

```bash
npm install -g 'git+https://github.com/alpacaloop/alpacaloop.git#main'
```

development checkout には `pnpm` を使います。以下の checkout command を実行する前に利用できるようにしてください。

development checkout:

```bash
git clone https://github.com/alpacaloop/alpacaloop.git
cd alpacaloop
pnpm install
pnpm build
```

この README では primary command として `alpaca ...` を使います。install 後は `alpacaloop ...` も command として使えます。issue comment command は `/alpaca` です。checkout から動かす場合は `pnpm alpaca ...` を使ってください。

help は次から見られます。

```bash
alpaca --help
alpaca <command> --help
alpaca docs list --with-description
alpaca docs show quick-start
```

全体 command reference は `alpaca help --all` または `man alpacaloop` を使ってください。

## Quick Start

最初の安全な評価では、CLI を install し、repository を 1 つ接続し、managed issue を 1 つ作成し、foreground cycle を 1 回実行して結果を確認してから、background service を有効化するか判断します。

始める前に、次を用意してください。

- GitHub、Gitea、GitLab のいずれかに接続された Git repository
- その provider の tracker credential
- Codex または Claude worker sign-in が少なくとも 1 つ、または `customWorkers` に設定した OpenAI 互換 custom worker endpoint
- issue として表現できる明確な最初の goal

### 1. Sign in a worker

`alpaca init` が worker sign-in を促す場合があります。先に実行することもできます。

```bash
alpaca auth setup
```

API key environment variable fallback を含む supported worker sign-in method は `alpaca docs show setup` で確認できます。

custom worker は `alpaca auth setup` を使いません。OpenAI 互換 endpoint と `${ENV}` secret を `alpaca.config.json` の `customWorkers` に設定します。

custom worker 設定例:

```json
{
  "customWorkers": {
    "kimi-k2": {
      "baseUrl": "https://api.moonshot.ai/v1",
      "model": "kimi-k2.6",
      "apiKey": "${MOONSHOT_API_KEY}",
      "requestParams": {
        "thinking": { "type": "disabled" }
      }
    }
  },
  "workers": {
    "default": ["kimi-k2"],
    "thinking": ["kimi-k2", "codex"]
  }
}
```

`apiKey` は Bearer auth の shorthand です。header 全体を明示したい場合だけ `headers.Authorization` を使ってください。両方の同時指定は invalid です。`requestParams` は AlpacaLoop が request を組み立てた後に OpenAI 互換 POST body へ shallow merge されます。URL query parameter や header には使われません。provider 固有パラメータは各 provider の API 仕様に従い、AlpacaLoop は値の意味までは検証しません。custom worker は OpenAI 互換 endpoint のみを扱い、AlpacaLoop は local model の起動・download・管理は行いません。Repo skill は `.agents/skills` と `skills` から読み込まれ、custom worker MCP server は Pi MCP adapter 経由で `.mcp.json` または `.pi/mcp.json` から読み込まれます。

### 2. Connect the repository

GitHub:

```bash
export ALPACA_GITHUB_TOKEN=...
# ローカル CLI credential を使う場合は gh auth login でも構いません。

alpaca init
alpaca doctor
```

Gitea:

```bash
export ALPACA_GITEA_USERNAME=...
export ALPACA_GITEA_PASSWORD=...

alpaca init --repo-provider gitea
alpaca doctor
```

Gitea repository を新規作成して登録する場合:

```bash
alpaca init --cwd ./my-repo --create-repo --repo-provider gitea --repo https://gitea.example.com/user/my-repo
```

GitLab:

```bash
export ALPACA_GITLAB_TOKEN=...
# `api` scope と repository access を持つ token を使ってください。

alpaca init
alpaca doctor
```

`alpaca doctor` は config、worker 認証、ラベル、repo 登録、リモートベースブランチの有無、workflow template の状態を確認します。

Git の user name、email、token、password は `alpaca.config.json` に入れないでください。この file は repository の管理対象です。background service の Bot commit には machine-local env を使います。

```bash
export ALPACA_GIT_USER_NAME="AlpacaLoop Bot"
export ALPACA_GIT_USER_EMAIL="bot@example.com"
```

これらの値は初回の `alpaca service enable` で service 定義に保存されます。既存 service の作成後に変更した場合は、`alpaca service enable --refresh-env` または `alpaca service restart --refresh-env` を実行してください。

worker workspace の dependency setup は `workspaces.setupCommand` で設定できます。詳細は `alpaca docs show config` を参照してください。

### 3. Create the first managed issue

tracker に投稿する前に確認したい場合は、先に local draft を保存します。表示された JSON path を確認した後、同じ draft を `--apply-draft` で publish します。

```bash
alpaca issue create --prompt "Fix flaky login tests." --save-draft
alpaca issue create --apply-draft ~/.alpaca/drafts/.../issue-create-....json
```

すぐ issue を作ってよい場合:

```bash
alpaca issue create --prompt "Fix flaky login tests."
```

通常の unscheduled issue には `AI: Ready` workflow label が付きます。scheduled、recurring、disabled issue option は別の queue state を設定します。詳しくは `alpaca docs show workflow-state` を参照してください。

### 4. Run one foreground cycle

continuous polling を有効化する前に、新しい issue を manual に 1 回処理します。

```bash
alpaca run --issue 123
```

background service が enabled の間は `alpaca run` を実行しないでください。一般的な one-cycle run が必要な場合は、先に option を確認してください。

```bash
alpaca run --help
```

### 5. Inspect the result

```bash
alpaca issue list --days 7 --limit 10
alpaca issue show --issue 123 --children 1 --limit 5
alpaca issue log show --issue 123 --tail 50
```

認証済み tracker user に assigned された issue だけを見る場合は `issue list` に `--me` を付けます。特定の assignee を見る場合は `--assignee <login>` を繰り返し指定します。

これらの command を first-run success check として使います。`issue list` と `issue show` は managed issue の current status、workflow label、workflow update、関連 child issue を表示します。`issue log show` はその issue の local log を表示します。issue が `AI: Ready` ではなくなっている場合は、まず visible status を読んでください。`AI: Running` は run または accepted continuation が進行中、`AI: Needs Human` は人間の入力待ち、`AI: Working in PR` は作業が pull request に移った状態です。元 issue の PR handoff comment には pull request への link が表示されるため、以降の review はそこから続けられます。label set 全体は `alpaca docs show workflow-state` で確認できます。

### 6. Enable background polling

foreground run を理解した後、service を有効化し、登録されて polling していることを確認します。

Linux / WSL2 の service mode には動作する systemd user session (`systemctl --user`) が必要です。WSL2 support は systemd 有効化済みを前提にします。使えない場合は foreground の `alpaca run` を続けてください。

```bash
alpaca service enable
alpaca service status
alpaca service log show --tail 50
```

Node / npm manager や global install path を変更した後は、`alpaca service enable` を再実行してください。保存済みの service 環境変数を保持したまま、使用中の `alpaca` command に合わせて service 定義を更新します。現在の shell 環境で保存済み service 環境変数を置き換えたい場合だけ、`alpaca service enable --refresh-env` または `alpaca service restart --refresh-env` を使います。

manual `alpaca run` に戻る前に service を disable します。

```bash
alpaca service disable
```

### Optional: create repository workflows

workflow template を作成または更新したい場合は、repository の目的を prompt に書き、同梱の workflow maintenance system workflow を明示します。

```bash
alpaca issue create --prompt "This repository is a TypeScript CLI for task automation. Create reusable workflows for bug fixes, PR reviews, unplanned maintenance, and follow-up work." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off
```

この例の `no_template` は、対象ごとの built-in default workflow を使います。

workflow maintenance を recurring にしたい場合や特定 worker を使いたい場合は、通常の `issue create` scheduling / worker options を使ってください。

## How It Works

1. `alpaca init` が repository を GitHub、Gitea、GitLab のいずれかに接続し、`alpaca.config.json` を作ります。
2. tracker issue が goal、context、constraint、done criteria を提供します。
3. `.alpaca/workflows/*.md` の workflow template が、planning、design、execution、review、unplanned work、follow-up、improvement など、次に必要な step へ worker を導きます。
4. AlpacaLoop が選択された configured worker を起動し、返された workflow contract を検証します。
5. label と managed comment によって current state、blocker、dependency、next action を tracker に反映します。

## Core Commands

| Command | Purpose |
| --- | --- |
| `alpaca init` | `alpaca.config.json` を作成または更新し、初期 sign-in 要件を解決する |
| `alpaca detach [--cwd <path>] [--purge]` | repository を service 管理から外す。通常は file を残し、`--purge` では repo-local AlpacaLoop file と workspace も削除する |
| `alpaca doctor` | config、worker、service connection、sign-in の状態を確認する |
| `alpaca publish [--path <path>] [--reviewer <name[,name...]>] [--no-merge] [--restart-service]` | local repository の修正内容を確定し、worker が使える場合は PR 本文も作成して、reviewer も `--no-merge` も指定がなければ commit / PR / merge で base branch へ反映する |
| `alpaca run [--issue 123]` | runnable な workflow issue を manual に 1 回だけ処理する。`--issue` は対象を特定 issue に絞る |
| `alpaca service enable` | background polling service を起動し、必要に応じて現在の CLI に合わせて service 定義を更新する |
| `alpaca service status` | service の状態と登録 repository を表示する |
| `alpaca service log show [--tail <lines>]` | background service log を表示する。必要に応じて最後の N 行に絞れる |
| `alpaca service restart` | 実行中の service work が終わってから、現在の CLI で service を再起動する |
| `alpaca service disable` | 実行中の service work が終わってから service を停止する |
| `alpaca state patch --dry-run --state open` | open issue の canonical workflow state comment を、tracker comment を更新せずに current schema へ migrate できるか preview する |
| `alpaca eject ...` | 同梱 system assets を編集用に repository へコピーする |
| `alpaca issue create ...` | managed issue の draft、review、review 済み draft の publish |
| `alpaca issue list` | 管理中 issue を確認する。自分の担当だけなら `--me`、override を見る場合は `--format text --view detailed`、tracker の issue 一覧を開く場合は `--web` を使う |
| `alpaca issue search --title "keyword" --state all --limit 10` | `issue list` / `issue show` で見つからない関連 issue を軽量に検索する |
| `alpaca issue show --issue 123` | 管理中 issue 1 件の詳細を確認する |
| `alpaca issue approve --issue 123` | 担当者として foreign input approval をコメント経由で承認する |
| `alpaca issue log list` | local issue run log を一覧する |
| `alpaca issue log show --issue 123 --tail 50` | issue 1 件の worker run log を読む。必要に応じて最後の N 行に絞れる |
| `alpaca issue log search --query "error" --context 2` | local issue run log を検索し、必要に応じて context 行を表示する |
| `alpaca issue followup --issue 123 [--prompt <text>] [--dry-run]` | 既存 issue から follow-up issue を作成する。`--prompt` の日時や頻度は通常の setup/autofill で schedule 推論でき、`--dry-run` で先に preview できる |
| `alpaca issue broadcast --message "..." --open --dry-run` | open queue issue へ shared comment を投稿する内容を preview する |
| `alpaca issue disable --issue 123` | 現在の workflow status を維持したまま `AI: Disabled` rule を追加する |
| `alpaca issue enable --issue 123` | 承認、開始、unlock、`AI: Ready` への移動はせず、`AI: Disabled` rule だけを外す |
| `alpaca issue unlock --issue 123` | `AI: Running` ownership を `AI: Ready` に戻す |
| `alpaca workflow create ...` | 再利用可能な workflow template を draft / review / 作成する |
| `alpaca workflow update ...` | 既存 workflow template の update を draft / review / 適用する |
| `alpaca workflow lint` | template 構造と nested reference を検証する。`--path` 指定時は required skill/MCP も厳格に検証し、全体 lint では capability 不足を warning として表示する |
| `alpaca workflow list` | target ごとに非 system workflow template を表示する。system workflow も見る場合は `--include-system` を追加する |
| `alpaca event-hook ...` | publish event hook を configure、create、register、list、remove、update、test する |
| `alpaca skill list` | worker が利用可能な skill と `requires.skills` に使う ref を JSON で表示する |
| `alpaca catalog topics list` | catalog 共通の topic ID と説明を JSON で表示する |
| `alpaca capability list/search` | skill と MCP を横断して discovery する。通常は workflow requires から除外された候補を隠し、必要時は `--include-excluded` で理由を確認する |
| `alpaca skill search <query> [--with-worker]` | インストール済み、catalog、marketplace の worker skill 候補を JSON で検索する。`--with-worker` で worker に semantic selection を依頼する |
| `alpaca skill install ...` | install 可能な skill 候補を worker 1つへダウンロードまたは配置する |
| `alpaca skill create ...` | worker に title / capability summary を作らせ、skill-resolution issue を review / 作成する |
| `alpaca skill catalog list` | repo-visible な install 可能 skill catalog entry を表示する |
| `alpaca skill catalog add ...` | install source を repo-local skill catalog に登録する |
| `alpaca skill catalog import-github ...` | GitHub の `SKILL.md` directory をまとめて skill catalog に登録する |
| `alpaca skill catalog remove ...` | repo-local skill catalog entry を削除する |
| `alpaca mcp list` | worker に設定済みの MCP server を JSON で表示する |
| `alpaca mcp search <query> [--with-worker]` | 設定済み、catalog-backed、discovery-only catalog entry の MCP 候補を検索する。`--with-worker` で worker に semantic selection を依頼する |
| `alpaca mcp install ...` | safeAutoInstall と server spec を持つ catalog entry で MCP 設定へ登録する |
| `alpaca mcp create ...` | worker に title / capability summary を作らせ、MCP-resolution issue を review / 作成する |
| `alpaca mcp verify` | `requires.mcp` に使う MCP ref を静的に検証する |
| `alpaca mcp catalog list/add/remove ...` | repo-visible な MCP catalog entry を管理する |
| `alpaca labels sync` | tracker に足りない managed label を作る |

`skill search` / `skill install --search` は installed inventory、repo/system catalog、provider marketplace を使います。`mcp search` / `mcp install --search` は installed inventory と MCP catalog を使います。runtime では GitHub registry metadata を検索しません。`servers` がない MCP catalog entry は discovery-only の手がかりであり、install するには server spec と `setup.safeAutoInstall: true` を catalog に追加してください。

capability 方針: `alpaca capability list/search` で skill と MCP を横断確認し、用途 fit、対象範囲の狭さ、source 信頼性、stars / updatedAt / createdAt などの品質シグナルで比較します。同じ目的を同程度に満たせる場合だけ skill を優先し、MCP の方が合う場合や live service/API/resource/server/tool access が必要な場合は MCP を使います。

background service はインストール済み AlpacaLoop package の version 変更を検知し、実行中の service work が完了してから自動的に再起動します。
現在の service work を待たずに要求した操作を即時実行する必要がある場合だけ、`alpaca service restart` または `alpaca service disable` に `--force` を付けてください。

## Workflow Templates

workflow template は `.alpaca/workflows/` と `__system/` の同梱 system workflow から読み込まれます。eject 済みの `.alpaca/workflows/__system/` ファイルは同梱版を上書きします。filename は識別子であり、どこで選択できるかは frontmatter の `targets`、自動選択対象かどうかは `autoSelect`、template update 権限は `updateMode` で宣言します。たとえば次のように置けます。

template 本文で別 template を呼び出す場合、`@workflow <template-path>` は参照先 template を planning 上の別 nested workflow step として展開したい時だけ使います。単に別の workflow document を読んで参考にしてほしい場合は、`.alpaca/workflows/...md` の path を本文中に通常の文章として書いてください。

template を削除または移動する前に、`alpaca workflow list --references-to <template.md>` で参照元を確認してください。`alpaca workflow delete --path <template.md>` は repo-local template だけを削除し、参照が残っている間は停止します。`--cleanup-references --save-draft` は、他 template を cascade delete せず、編集可能な参照元 template の cleanup update を review 用 draft として作成します。

```text
.alpaca/workflows/
  engineering/implementation.md
  docs/maintenance.md
  review/pull-request.md
  unplanned/remediation-verification-blocker.md
  workflow/retrospective.md
```

再利用可能な template を書く、または編集する前に `alpaca docs show workflow-template-authoring` を実行し、template の責任範囲、必要な形、validation step を確認してください。repository 固有の authoring preference は `workflow-create` system prompt で調整します。system workflow template ではありません。

`workflow create` で template を作成または scaffold し、interactive terminal では `workflow update --prompt <text>` で対象 template を選んで改善し、対象が分かっている場合は `workflow update --path <template.md> --prompt <text>` で明示的に指定できます。`workflow lint --path <template.md>` で対象 template と nested workflow の構造、metadata、required skill/MCP ref を厳格に検証し、全体の `workflow lint` では未選択 template の required capability 不足を warning として表示します。`workflow list --target <target>` で非 system template を確認し、system workflow も含める場合は `workflow list --include-system --target <target>` を使い、`eject workflows` で同梱 system workflow template（`no_template` の default workflow を含む）を `.alpaca/workflows/__system/` にコピーし、`eject system-prompts` で任意の repository guidance prompt を `.alpaca/system-prompts/` にコピーし、`eject catalog` で同梱 system skill、MCP、catalog metadata を `.alpaca/catalog/__system/{skill.json,mcp.json,metadata.json}` にコピーします。service automation は configured base branch から workflow template と system prompt file を読み込むため、local workflow edit は `alpaca publish --path .alpaca/workflows`、local system prompt edit は `alpaca publish --path .alpaca/system-prompts`、`paths.systemPrompts` で別 path を指定している場合はその path も publish してください。workflow selector は `auto`、`auto_select`、`no_template`、path を受けます。`auto` は候補 template の使用、`no_template` による built-in default workflow の使用、不足 template の要求を worker が判断します。`auto_select` は既存候補か `no_template` のみを選び、候補がない場合は worker を呼ばず `no_template` へ fallback し、対象 target の built-in default workflow を使います。候補 template を使う場合は AlpacaLoop が planning 前に fit review を行います。通常実行で worker が不足 template を要求した場合は blocking な `missing-workflow-template` setup issue を作ります。prompt mode の issue creation は未解決の auto / auto_select workflow selection を保存するため、親 issue 作成後に workflow setup が選択を扱います。選択 template が親リクエストを狭めたり矛盾したりする場合は blocking な `workflow-template-fit` setup issue で、より適切な再利用可能 template を準備します。`__system/workflow-maintenance.md` は issue prompt から再利用可能な workflow template を作成または更新するための明示指定専用 system workflow です。`--workflow`、`--default-worker`、`--thinking-worker`、`--base-branch`、`--recurring-max-active-children`、`--recurring-update-child-title-after-plan`、`--workflow-start-new-plan`、`--workflow-start-replan`、`--workflow-start-scope`、`--run-at`、`--run-after`、`--every`、`--cron`、`--first-run-*`、`--stop-*`、`--pr-workflow`、`--unplanned-workflow`、`--issue-completion-target`、`--pr-review`、`--pr-merge`、`--followup-proposal`、`--followup-proposal-approval`、`--followup-preferred-workflow-template`、`--followup-auto-maintain-templates`、`--followup-max-main-work-issues`、`--followup-max-maintenance-issues` などの sticky override も使えます。

任意の system prompt file は `alpaca eject system-prompts` 後に `.alpaca/system-prompts/` に配置されます。worker convention、workflow 全体の convention、workflow planning/review preference、current-step execution preference、workflow closing の完了報告・close audit、workflow template authoring preference、event hook create preference、issue create style、human handoff style、follow-up recommendation guidance、merge integration preference など、repo 固有の guidance を追加するためのものです。既存の `.claude` などに guidance がある場合は、`alpaca.config.json` の `paths.systemPrompts.<name>` で repo-relative な `.md` path を指定できます。

定期実行の親 issue は待機中 `AI: Recurring` になり、due になると open recurring child が `recurring.maxActiveChildren` 未満の間だけ service が blocking child issue を作成し、上限到達時は child を作らず親を次回 schedule へ進めます。recurring auto-stop が due になった場合、open recurring child が残っていれば child 完了後に親 issue を閉じます。`aiWorkflowOptionAutofill: on` では、親 issue の fresh comment を child 作成前に autofill するため、「1週間後に閉じて」のような依頼を先に親の auto-stop policy へ反映できます。

Follow-up workflow は、元 issue / PR の完了後に別 issue を作成または再利用します。repo 全体の default は `followup.proposalPolicy`（`off`、`if_needed`、`always`）、`followup.proposalApproval`（`auto`、`confirm`、`confirm_if_needed`）、planned child issue への継承方針 `followup.childIssuePolicy`（`inherit` または `off`、default `inherit`）、自動 follow-up issue の category 別上限 `followup.maxIssuesPerSource`（default `{ mainWork: 2, maintenance: 2 }`）、優先候補 `followup.preferredWorkflowTemplates`、template 自動整備の可否 `followup.autoMaintainTemplates` で設定します。自動 recommendation は、元依頼・メイン作業の続きを `mainWork`、workflow / prompt / skill / MCP / Codex / Claude / worker 環境の改善を `maintenance` として分類します。自動 follow-up publication には fresh な `workflow_closing` audit が必要です。PR merge finalization では、AlpacaLoop が source または base workspace を同期し、PR head または merge commit を検証してから recommendation を公開します。検証できない場合は自動 follow-up 作成を止め、人間の確認を求めます。`/alpaca --followup-proposal if_needed` は完了時判断を有効化し、`--followup-proposal always` は常に候補生成、`--followup-proposal off` は無効化します。`--followup-proposal-approval <auto|confirm|confirm_if_needed|default>` で候補を即 issue 化するか、確認コメントで止めるかを制御します。pending proposal の承認時は、proposal 後に追加されたユーザーコメントを review worker が先に反映するため、`AI: Follow-up` label を付ける前に候補の追加・修正・削除をコメントで依頼できます。`alpaca issue followup --issue <id> --prompt <text>` は独立した follow-up issue を即時作成し、依頼文をその issue body に保存します。日時や頻度を含む依頼文は通常の setup/autofill で schedule 推論できます。`--followup-preferred-workflow-template <path|no_template[,path...]|default>` は recommendation prompt に最優先候補として渡すだけで、repeatable / comma-separated に対応し、allowlist でも作成保証でもありません。`--followup-max-main-work-issues <0..5|default>` と `--followup-max-maintenance-issues <0..5|default>` は、その source item だけの自動 follow-up category 上限を上書きします。`autoMaintainTemplates: true` では follow-up issue の workflow selection が不足または改善が必要な template を request できる `auto` を使い、default の `false` では `auto_select` を使います。default が `AI: Follow-up` の `ticketTracker.workflowLabels.aiFollowUp` label を付けると、pending proposal があれば承認、なければ明示的な follow-up request として扱われます。

## Publish Event Hooks

詳細は `alpaca docs show event-hooks` に集約しています。`alpaca event-hook test` は実送信などの副作用を起こす可能性があります。

## Configuration

`alpaca.config.json` は通常 `init` が生成します。主な設定グループは次です。

- 出力言語と表示 / スケジュール用タイムゾーン
- repository / tracker の接続先
- default / thinking worker の順序と machine-local sign-in
- service の polling 間隔と並列度
- workflow label と approval 振る舞い
- dependency / pull request automation
- repo scope publish event hook

CLI から読める設定説明は `alpaca docs show config` を参照してください。issue 単位の workflow override と schedule は `alpaca docs show workflow-options` を参照してください。

## Docs

CLI から読める reference topic は `alpaca docs list --with-description` で一覧できます。1件を読む場合は `alpaca docs show <topic>`、検索する場合は `alpaca docs search <query>`、全文を読む前に見出しだけ確認する場合は `alpaca docs search <query> --view headings` を使います。

最初に見る topic:

- `quick-start`: install から最初の managed issue までの最短手順
- `install`: CLI installation と local checkout
- `setup`: repository initialization、worker sign-in、health check
- `issues`: issue creation、search、inspection、approval、follow-up、log、unlock
- `workflow-template-authoring`: 再利用可能な workflow template の作成ルール
- `workflow-state`: label、workflow update、resume behavior

## Development

contributor setup、checks、documentation boundaries は [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。

```bash
pnpm install
pnpm build
pnpm hooks:install
pnpm typecheck
pnpm test
pnpm verify
```

## License

MIT. [LICENSE](LICENSE) を参照してください。
