@harnessforce/claude-code-plugin 0.1.0 → 0.2.0

package/skills/record-run/SKILL.md

@@ -1,66 +1,29 @@
 ---
 name: record-run
-description: HarnessforceのIssue（ENG-42のような識別子）に取り組む作業で、HarnessforceのMCP serverのtoolを使い、このsessionをRunとして登録し、Plan、Decision、Definition of Doneの充足を記録する。Issueに取り組み始めるとき、Issueを指定されずに変更をcommitする作業を始めるとき、方針を変えるとき、作業を終えるときに使う。
+description: For work on a Harnessforce Issue (an identifier such as ENG-42), use the tools of the Harnessforce MCP server to register this session as a Run and to close the Run when the work ends. Use it when you start work on an Issue and when you finish the work.
 ---
 
-# HarnessforceのIssueの作業を記録する
+# Record work on a Harnessforce Issue
 
-HarnessforceのMCP serverのtoolで、作業をIssueに結び付けて記録する。toolを初めて使うときは、ブラウザでのログインとWorkspaceの選択を求められる。
+Use the tools of the Harnessforce MCP server to link the work to the Issue. The first time you use a tool, you are asked to log in in the browser and choose a Workspace.
 
-## 作業の開始時
+## At the start of the work
 
-利用者がIssueを示していなければ、先に下の「Issueを指定されていない場合」に従う。
+1. Pass the value of `harnessforce session_id: <session_id>` in the context as `session_id`, and register the Run with `start_run`. The Harnessforce plugin adds this line to the context at session start. If there are several, use the last one added. The input is the Issue identifier (`issue_identifier`), `agent` (`claude_code`), and `session_id`. If you know the repository, branch, and commit you are working on, pass them too. Keep the returned `run_id` until the end. If the line is missing from the context, follow "When the session ID is missing" below.
+2. Check the Issue with `get_issue`.
 
-1. contextにある`harnessforce session_id: <session_id>`の値を`session_id`として渡し、`start_run`でRunを登録する。この行はHarnessforceのpluginがsessionの開始時にcontextへ加える。複数あれば、最後に加えられたものを使う。入力は、Issueの識別子（`issue_identifier`）、`agent`（`claude_code`）、`session_id`とする。作業しているrepository、branch、commitが分かれば併せて渡す。返された`run_id`を終了時まで控えておく。contextにこの行が無い場合は、下の「session IDが無い場合」に従う。
-2. `get_issue`で、Issue、Plan、Definition of Doneを確認する。nativeのIssueなら、下の「nativeのIssueの状態」に従う。Planは状態（現行か`proposed`か）で区別されている。
-3. 現行のPlanも`proposed`のPlanも無ければ、作業の方針を`record_plan`で記録する。本文はmarkdownで書く。
+## When the session ID changes
 
-## 作業の途中
+- If the value of the last `harnessforce session_id:` in the context differs from the value you passed to the previous `start_run` (for example after forking the conversation or running `/clear`), call `start_run` once more with the new value before continuing, and use the returned `run_id` for later `complete_run` calls.
 
-- 方針を変えたとき、または選択肢から選んだときは、`record_decision`で記録する。題（`title`）、決めたこと（`decision`）、理由（`rationale`）を必ず書き、検討した選択肢があれば`alternatives`に書く。
+## At the end of the work
 
-## session IDが変わったとき
+- Call `complete_run` with the `run_id`.
 
-- contextの最後の`harnessforce session_id:`の値が、直前の`start_run`に渡した値と異なる（会話をforkしたとき、`/clear`したときなど）場合は、作業を続ける前に新しい値で`start_run`をもう1度呼び、返された`run_id`を以後の`complete_run`に使う。
+## When the session ID is missing
 
-## 作業の終了時
+- If the context has no `harnessforce session_id:` line, do not guess and pass a session ID, and do not call `start_run` or `complete_run`. `get_issue` does not depend on the Run, so continue with it. Tell the user once: "The Harnessforce hook is not running, so the Run cannot be recorded. Run `/harnessforce:setup`".
 
-- `complete_run`に`run_id`と、`get_issue`が返したDefinition of Doneの項目ごとの充足（`item_id`と、満たしたなら`met`、満たしていないなら`unmet`）を渡す。Definition of Doneの項目が無い場合は、項目を渡さない。
+## What is not recorded
 
-## Issueを指定されていない場合
-
-利用者がIssueを示さずに作業を始めたら、Issueを作るかを利用者に尋ねる。Issueを作るのは、利用者が承諾した後だけとする。
-
-1. 次のすべてに当たる場合だけ尋ねる。
-   - 利用者がIssueの識別子を示していない。現在のbranch名が`ENG-42`、`eng-42-login`、`gh-45-fix`のような識別子を含み、`get_issue`でそのIssueを解決できたら（`gh-<番号>`は、そのrepositoryの`<owner>/<repo>#<番号>`として渡す）、そのIssueを示されたものとして「作業の開始時」に進み、尋ねない。`not_found`なら識別子が無い場合と同じに扱う。
-   - 作業が変更をcommitするものである。調べもの、質問への回答、計画だけの会話では尋ねない。
-   - contextに`harnessforce session_id:`の行がある。
-   - contextの最後の`harnessforce session_id:`の値ごとに、同じ値で尋ねるのは1回だけとする。利用者が断ったら、同じ値の間は再び尋ねない。forkや`/clear`で値が変わったら、改めて尋ねてよい。
-2. 既存のIssueを先に示す。作業の要約から、Issueのtitleに現れそうな語を最大3つ選び、語ごとに`list_issues`を、`q`を`-status:done,canceled {語}`、`sort`を`updated`として1回ずつ呼ぶ。自由文は複数の語ではそのすべてを含むIssueにだけ一致するため、語を分けて呼ぶ。結果を合わせて重複を除き、更新の新しい順に最大5件を候補として示す。利用者が候補を選んだら、Issueを作らずにそのIssueで「作業の開始時」に進む。
-3. 候補に当たるものが無ければ、作る案を示す。
-   - title: 作業の要約。80文字以内。
-   - 説明: 目的と完了の条件の箇条書き。
-   - Project: `list_projects`を`q`を`status:active`として呼び、1件ならそれを、2件以上なら利用者に選ばせる。0件ならIssueを作らず、その旨を伝える。
-   - titleと説明には、promptの本文、file path、command、secretを写さない。titleは一覧とURLに現れ、説明より広く読まれる。
-   - 外部のIssue管理ツールを使うチームには、「Harnessforceにだけ作られ、外部のツールには書き戻されません」と伝える。
-4. 利用者が案を承諾した場合だけ、`create_issue`でIssueを作り、返されたidentifierで「作業の開始時」の`start_run`を呼ぶ。利用者が案を直したら、直した値で作る。承諾は会話の中の利用者の明示の返答とする。非対話の実行や利用者のいない自動の実行では、返答を得られないため作らない。
-5. 作れない場合と失敗した場合:
-   - `create_issue`か、候補を選んだ後の`start_run`が`forbidden`（Viewerのtoken、閲覧のみのWorkspaceの`workspace_read_only`を含む）を返したら、作れない理由をそのまま伝え、同じsession IDでは再び尋ねない。
-   - `create_issue`を再試行しない。再試行するとIssueが2件作られうる。timeoutなどで結果が分からなければ、`list_issues`で案のtitleを自由文に検索し、titleが完全に一致し、作成時刻が呼び出しの後のIssueが見つかればそれを使う。見つからなければ、作れなかったことを伝える。
-   - `create_issue`が成功して`start_run`だけが失敗したら、作ったIssueのidentifierを伝え、Issueを作り直さない。
-6. `create_project`、`create_milestone`、`create_cycle`、`create_objective`を自らの判断で呼ばない。目標日、所属、Priority、Assigneeも自ら変えない。これらは計画の変更であり、利用者が会話の中で明示に指示した場合だけ、指示どおりに呼ぶ。
-
-## nativeのIssueの状態
-
-- nativeのIssue（`get_issue`の`external`が`null`のIssue）で、作業を始めた時点の状態が`backlog`か`unstarted`なら、`start_run`の後に「状態を『進行中』にしますか」と尋ね、承諾した場合だけ`update_issue`で状態を`started`に変える。`update_issue`には、`get_issue`が返したIssueの`version`（`definition_of_done.version`ではない）と、変えない他の属性の現在の値を併せて渡す。
-- 作業を終える時点で、利用者が仕事の完了を示していれば、`complete_run`の後に「状態を『完了』にしますか」と尋ね、承諾した場合だけ状態を`done`に変える。Pull Requestを開いただけで、mergeされていない場合は尋ねない。
-- 外部由来のIssueの状態は変えない。状態の正本は外部のツールである。GitHub IssuesのIssueでは、利用者がPull Requestの本文を書く際の文面として`Closes #<番号>`を提案してよい。agentがPull RequestとIssueを自ら結び付ける操作の代わりにはしない。
-- `update_issue`が`conflict`を返したら、`get_issue`で読み直して伝え、1回だけ尋ね直す。再び`conflict`なら、そのことを伝えて終える。
-
-## session IDが無い場合
-
-- contextに`harnessforce session_id:`の行が無ければ、session IDを推測して渡さず、`start_run`と`complete_run`を呼ばない。`get_issue`、`record_plan`、`record_decision`はRunに依らないため続ける。利用者には「Harnessforceのhookが動いていないため、Runを記録できません。`/harnessforce:setup`を実行してください」と1回だけ伝える。
-
-## 記録の扱い
-
-- agentが記録したPlan、Decision、充足は`proposed`として保存され、人が承認するまで確定しない。記録したことを、確定したこととして利用者へ伝えない。
+- Harnessforce does not record a Plan, a Decision, or a Definition of Done, and the Harnessforce tools do not create or edit Issues. Issues are GitHub Issues. Harnessforce shows the sessions, Pull Requests, and CI results linked to an Issue without any record from you.

package/skills/using-harnessforce/SKILL.md

@@ -1,54 +1,54 @@
 ---
 name: using-harnessforce
-description: Harnessforceのhookが入った環境でsessionを始めたとき、HarnessforceのIssue（ENG-42のような識別子）に取り組む作業を始めるとき、Harnessforceが何を記録し何を収集しないかを尋ねられたときに使う。sessionの開始時にhookがこの本文をcontextへ注入する。
+description: Use when starting a session in an environment with the Harnessforce hook, when starting work on an Issue, or when asked what is recorded or collected. The hook injects this text into the context at session start.
 ---
 
-# Harnessforceを使う
+# Using Harnessforce
 
-このsessionにはHarnessforceのhookが入っている。Harnessforceは、人とAIの作業をIssueに結び付けて記録する。次の規則に従う。
+This session has the Harnessforce hook installed. Harnessforce links the work of people and AI to Issues and records it. Follow these rules.
 
-## 何を記録するか
+## What is recorded
 
-- session registration: agent、session ID、repository、branch、commit、開始時刻、最初のprompt ID。
-- config snapshot: 利用中の設定の構成（Claude Codeだけ）。
-- OTelのテレメトリ: 利用者の設定で送るもの。
-- Issueに取り組む作業で`record-run`が記録する、Plan、Decision、Definition of Doneの充足。人が承認するまで確定しない。
+- Session registration: agent, session ID, repository, branch, commit, start time, and the first prompt ID.
+- Config snapshot: the structure of the configuration in use (Claude Code only).
+- OTel telemetry: what the user chooses to send.
+- For work on an Issue, `record-run` registers the session as a Run and closes it. It records no Plan, Decision, or Definition of Done.
 
-## 何を収集しないか
+## What is not collected
 
-- prompt、応答、toolの入出力、code diffの本文は、利用者が`--send-content`で選び、Workspaceがopt-inした場合だけ届く。既定では収集しない。
-- MCPのtoolの入力にも記録にも、これらの本文、secret、環境変数の値を含めない。
+- Prompts, responses, tool input and output, and the body of code diffs arrive only when the user opts in with `--send-content` and the Workspace has opted in. They are not collected by default.
+- Never put these contents, secrets, or environment variable values in MCP tool input or in a record.
 
-## どのhookが何を送るか
+## Which hook sends what
 
-- SessionStart: session registrationとconfig snapshot（Codexはsession registrationだけ）。
-- UserPromptSubmit: 最初のpromptでの再送（Claude Codeだけ）。
-- hookは失敗してもsessionを止めない。送れない状態のときは、hookが警告を1行表示する。警告が出たら利用者に伝える。
+- SessionStart: session registration and the config snapshot (Codex sends session registration only).
+- UserPromptSubmit: resends on the first prompt (Claude Code only).
+- A failing hook never stops the session. When the hook cannot send, it shows a one-line warning. Tell the user when a warning appears.
 
-## どのskillとtoolをいつ使うか
+## Which skill and tool to use, and when
 
-- IssueのIDを指定された作業、または環境変数`HARNESSFORCE_ISSUE`がある作業は、`record-run`に従い、`start_run`、`get_issue`、`record_plan`、`record_decision`、`complete_run`を使う。skillを読み込めないagentは、同じ順にtoolを呼ぶ。
-- `start_run`には、contextの`harnessforce session_id:`の行の値を渡す。複数あれば最後の値を使う。行が無ければ、session IDを推測せず、`start_run`と`complete_run`を呼ばない。
-- `/harnessforce:tune`の分析は`propose-improvements`を使う。
-- Issueが指定されていない作業では、Runの記録を始めない。
+- For work on a specified Issue ID, or when the environment variable `HARNESSFORCE_ISSUE` is set, follow `record-run` and use `start_run`, `get_issue`, and `complete_run`. An agent that cannot load the skill calls the tools in the same order.
+- Pass the value of the `harnessforce session_id:` line in the context to `start_run`. If there are several, use the last one. If the line is missing, do not guess the session ID, and do not call `start_run` or `complete_run`.
+- Use `propose-improvements` for the analysis of `/harnessforce:tune`.
+- When no Issue is specified, do not start recording a Run.
 
 ## Red Flags
 
-次の考えが浮かんだら、立ち止まる。
+Stop when one of these thoughts comes up.
 
-| 考え | 現実 |
+| Thought | Reality |
 | --- | --- |
-| 小さな作業なので記録は要らない | Issueが指定された作業は、大きさによらず記録する |
-| session IDの行が無いが、推測して`start_run`を呼ぶ | 推測しない。Runがsessionと結び付かなくなる |
-| 本文を要約して渡せば記録の役に立つ | 本文はtoolに渡さない。収集しない範囲を超える |
-| 警告が出たが、気にしなくてよい | 送れていない。利用者に伝える |
+| An Issue was specified, but the work is small, so recording is unnecessary | Work on a specified Issue is recorded regardless of its size |
+| The session ID line is missing, so I will guess it and call `start_run` | Do not guess. The Run would no longer be linked to the session |
+| Summarizing the content before recording would help | Do not pass content to the tool. It goes beyond what is collected |
+| A warning appeared, but I can ignore it | Sending is not working. Tell the user |
 
-## 優先順位
+## Priority
 
-1. 利用者の指示（CLAUDE.md、AGENTS.md、直接の依頼）。利用者が記録を止めるよう指示したら、Runの記録を止める。
-2. この導入文。
-3. 既定の動作。
+1. The user's instructions (CLAUDE.md, AGENTS.md, direct requests). If the user tells you to stop recording, stop recording the Run.
+2. This introduction.
+3. Default behavior.
 
-## subagent
+## Subagents
 
-親から特定の作業だけを委譲されたsubagentは、この導入文に従ってRunを登録しない。Runの登録は親が行う。
+A subagent that was delegated only a specific task by its parent does not register a Run by following this introduction. The parent registers the Run.