involute

Files (1)

• SKILL.md

SKILL.md (first lines)

# Involute (overview)

Involute stores long-lived work identity, contracts, links, status, and evidence. Your coding agent is the working surface — do **not** treat Involute as a TODO list or dump local plan steps into it.

Connect: Streamable HTTP MCP at `http://127.0.0.1:4200/mcp` (local) with `Authorization: Bearer inv_agent_…`. Full client matrix in `docs/agent-setup.md`. Prefer `/mcp/readonly` until you need to create or claim work. **Never commit tokens.**

## Skill index

| Skill | When |
|---|---|
| [search-work](../search-work/SKILL.md) | Find existing work before creating anything |
| [get-context](../get-context/SKILL.md) | Load contract, ancestors, blockers, claim, audits |
| [list-ready](../list-ready/SKILL.md) | Committed, unblocked, unclaimed work |
| [propose-work](../propose-work/SKILL.md) | Candidate proposal with optional initial_state ('REVIEW'/'STARTED'/'UNSTARTED') |
| [file-bug](../file-bug/SKILL.md) | Type: Bug — committed directly, never Candidates; priority required for SLA |
| [claim-work](../claim-work/SKILL.md) | Lease ready work after the user chooses it |
| [update-work](../update-work/SKILL.md) | Fields with `expected_revision`; committed contracts via `work_propose_amendment` |
| [report-run](../report-run/SKILL.md) | Phase / block / complete (In Review, never Done) |
| [attach-evidence](../attach-evidence/SKILL.md) | PR/test/artifact URL |
| [agent-setup](../agent-setup/SKILL.md) | Wire MCP + Bearer token (secrets stay out of git) |
| [project-onboarding](../project-onboarding/SKILL.md) | Initial repo onboarding, 3-tier tree, reality alignment |

## Hard rules (all skills)

1. Search before propose. Duplicate titles are a failure.
2. Fuzzy discoveries go through `work_propose`, never straight to committed issues — **except Type: Bug** (`work_file_bug` or `work_propose` with `labels: ['bug']`, `priority` 1–4, `steps_to_reproduce`, `acceptance`, and a parent): that is committed directly and does not go to Candidates. Set `initial_state: 'REVIEW'` for completed features so they commit directly to `In Review`; candidate `initial_state` cannot be `COMPLETED` or `CANCELED`.
3. Do not create a child unless it can be independently accepted.
4. Do not write local TODOs, grep results, or shell steps into Involute.
5. `work_claim` after the user chooses a ready item — do not grab the whole queue. Use the returned `suggested_branch` verbatim as your git branch name; never invent branch names containing issue identifiers. Alias-prefixed references (e.g. `LUM-398` on a repo whose PROJECT node has `alias: LUM`) are also accepted and canonicalize to the team key (`INV-398`).
6. `work_commit` and candidate rejection are **human** actions. Agents stop and ask.
7. **Work state changes without telling you — status is read, not remembered.** Before starting a turn or stating any item's status, read `agent_inbox` (and pass `ack: [...]` to clear handled notifications) or `work_get_context` (`commitmentStatus`); never state candidate/committed status from memory. When you have unread notifications, non-inbox MCP tool responses piggyback an `unread_decisions` summary (`{ count, latest, hint }`) — treat it as a reminder only (`agent_inbox` and `commitmentStatus` remain the source of truth, and piggybacking does not mark notifications read).
8. Run complete is not work accepted. **Never** move work to Done yourself.
9. Expanding scope requires `work_update` with `expected_revision` or a new candidate linked `DISCOVERED_DURING`.
10. Keep plans/findings local. Sync only phases, blockers, decisions, and evidence pointers. When attaching a report or postmortem to work (`work_attach_file`), pass plain UTF-8 (`encoding: 'utf-8'`) or upload local disk files directly with `involute work attach-file <id> <path>` — never `base64` + `cat` a local file through LLM tokens, and use `mode: 'overwrite' | 'append' | 'delete'` instead of leaving truncated or `part1..N` attachments.

## Unplanned Work & Hotfix Protocol (即时热修与计划外工作自动闭环法则)

Any bugfix or unplanned modification touching product source code MUST adhere to this automatic reflex:

1. **触发时机 (Trigger)**:
   当 Agent 在排查或重构中，修改了超出当前 Claim 任务原始范围的代码（例如修复了底层公共库、修了系统服务 Bug、更新了通信协议）。
2. **执行原则（动量优先 - Momentum First）**:
   Agent 可以先就地改好代码、通过本地测试，绝不打断修复心流与工程动量。
3. **自动化闭环（禁止幽灵代码 - No Ghost Fixes）**:
   - **在向用户输出回复前，Agent 必须强制调用 `work_propose`**；
   - 参数固定为：
     - `kind: 'ISSUE'`
     - `related_work_id: <当前任务/父里程碑>`
     - `related_work_type: 'DISCOVERED_DURING'`
     - 若是 bug：`work_file_bug`（必带 `priority` 1–4、`steps_to_reproduce` 与 `acceptance`），直接承诺、不进 Candidates
   - 自动生成标准的结构化中文描述（定位、根因与范围、验证方案）。
4. **汇报义务 (Reporting Accountability)**:
   在最终向用户回复时，必须附带一条：
   > *“排查过程中顺带修复了底层 Bug，已自动向 Involute 提报 `INV-xxx`（DISCOVERED_DURING），证据已挂载。”*

## Typical loop

```text
agent_inbox (read & ack decisions) → work_list_ready / work_search → work_get_context → work_claim
(local plan — do not upload)
work_update or work_propose for newly confirmed work
run_report + evidence(attach) → In Review (human accepts → Done)
```

From fakechris/Involute, Apache-2.0.

More from fakechris/Involute