规划师
- 作者仓库星标 2
- 作者仓库 anton
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @wcygan · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Planner
Anton-local skill for the in-repo plan lifecycle. Owns four workflows: **new**, **list**, **update**, **close**. Plans live at `context/plans/NNNN-kebab-slug.md` and are **mutable** — the body is edited as work progresses, tasks get checked off, the log grows.
## Why this skill exists
Anton already has two complementary persistence layers:
- **ADRs** (`context/adrs/`) — immutable decisions. Answer *why*.
- **Auto-memory** — ephemeral cross-session hints. Answer *what did I just learn*.
- **Git log** — immutable commits. Answer *what changed*.
But there's a missing layer: the multi-session initiative — "adopt Longhorn", "migrate Tailscale", "roll out OpenTelemetry". These span many commits and several sessions. Memory is too ephemeral (decays as new entries push it out); git log is too coarse (no sense of what's *next*); ADRs are too rigid (decisions, not execution state).
Plans fill that gap. They're **in-repo** (survive across sessions without relying on memory), **mutable** (task lists churn), **discoverable at session start** (via the SessionStart hook), and **trunk-compatible** (just files edited on main — no long-lived branches).
The skill is anton-local. Format is intentionally compatible with the global `context-repo` skill but this skill never delegates to that one.
## Hard rules
- **Plans are mutable — but carefully.** Task lists, logs, and status flip freely. **Goal** and **Acceptance criteria** should change only when the scope itself changes; substantial scope changes should `close` the plan as abandoned and `new` a replacement rather than quietly mutating the intent.
- **Numbers are never reused.** Next number is `max(existing) + 1`, zero-padded to four digits.
- **Active statuses** are `Draft`, `In-progress`, `Blocked`. Terminal statuses are `Done`, `Abandoned`. Only active plans are surfaced in the SessionStart index.
- **Close on done.** Plans should not drift into a permanent In-progress state. If nothing has changed in >30 days, mark `Blocked` with a reason, or `close` as abandoned.
- **Plans point at ground truth; they do not duplicate it.** Renovate dashboards, Flux kustomization status, memory entries — reference them, don't mirror them.
- **Plans do not replace ADRs.** If a plan surfaces a durable architectural decision during execution, hand off to the `adr` skill to record it. Link the new ADR from the plan's References section.
References:
- Field reference, status enum, and immutability rules → [conventions](references/conventions.md)
- Canonical template for new plans → [template](references/template.md)
## Workflow — `new`
Triggered by:
- The user says "open a plan for X" / "start tracking X" / `/planner new "<title>"`
- The user wants to promote an in-flight memory entry into a durable plan
- The user commits to a multi-session migration, rollout, or refactor
Before running the full workflow, **ask**: does this really need a plan? If the work is a single commit, a Renovate PR, or something that will finish in this session, say so and decline. Plans are for work that spans sessions.
### Steps
1. **Allocate the next number.** `Glob('context/plans/0[0-9][0-9][0-9]-*.md')`. Sort. Next number is `max + 1`, zero-padded to 4 digits. Never reuse.
2. **Generate the slug.** Lowercase, kebab-case, drop articles/prepositions, 4–6 meaningful words. Example: "Migrate Tailscale to the new tailnet" → `migrate-tailscale-new-tailnet` → `0001-migrate-tailscale-new-tailnet.md`.
3. **Interview the user.** Ask only for what isn't already known:
- **Title** (one short sentence, imperative or descriptive)
- **Goal** (one paragraph — what "done" looks like in plain language)
- **Acceptance criteria** (2–5 outcome bullets, not tasks — conditions that must be true at close)
- **Initial task list** (3–10 concrete next steps; more will accrue during execution)
- **`affects`** — same category list as ADRs (`storage`, `observability`, `networking`, `security`, `compute`, `all`, etc.)
- **`intent`** — `concrete-need` / `learning` / `unknown`
- **`related-adrs`** — list of ADR NNNNs that scope this plan (usually the decision that triggered the work)
- **`review-by`** — required for `intent: learning`, optional otherwise. Date to re-evaluate.
- **Initial log entry** — one-line note of *why now*, to anchor the history.
4. **Write the plan file** at `context/plans/NNNN-slug.md` using the shape from [template](references/template.md). Set `status: In-progress` (or `Draft` if the user is still shaping the goal), `opened: YYYY-MM-DD` to today.
5. **If this replaces an in-flight memory entry**, tell the user to remove the memory file (auto-memory is not self-cleaning). Cite the exact path. The plan supersedes the memory.
6. **Confirm to the user** with the file path, the plan number, and a reminder that the SessionStart hook will pick it up on the next session.
## Workflow — `list`
Triggered by:
- `/planner list` — default, shows active plans only
- `/planner list --all` — include terminal (Done / Abandoned)
- `/planner list --status <X>` or `--affects <X>` — filter
### Steps
1. `Glob('context/plans/0[0-9][0-9][0-9]-*.md')`.
2. Read frontmatter of each. Extract `status`, `opened`, `closed`, `affects`, `intent`, `related-adrs`, `review-by`, and the H1 title.
3. Apply filters:
- Default: keep only `Draft` / `In-progress` / `Blocked`
- `--all`: no filter
- `--status X`: case-insensitive exact match
- `--affects X`: substring match on the `affects:` field
4. Format as a markdown table sorted by NNNN. Columns: #, Title, Status, Opened, Review-by, Related ADRs.
5. If a plan has `review-by` ≤ today and status is still active, flag it with `⚠` in the Status column.
## Workflow — `update`
Triggered by:
- `/planner update <NNNN>` — the user wants to edit an existing plan
- The user says "check off X on plan NNNN" / "log Y on plan NNNN" / "mark NNNN blocked"
This is the most-used workflow. The skill doesn't wrap every possible edit — it knows the plan's shape and uses the ordinary `Edit` tool to make targeted changes.
### Common edit recipes
- **Check off a task.** Find the task line in the **Tasks** section and replace `- [ ] text` with `- [x] text` (preserve exact indentation). Then append a one-line entry to the **Log** with today's date.
- **Add a task.** Append to the **Tasks** section under the appropriate heading (or at the end). Keep the task imperative, concrete, and verifiable.
- **Log a decision or surprise.** Append to the **Log** section. Format: `- YYYY-MM-DD: <one sentence>`. The log is append-only; never rewrite past entries.
- **Flip to `Blocked`.** Edit the `status:` line in frontmatter and append a Log entry naming the blocker. Don't lose visibility — blocked plans should name a concrete unblock condition in the Log.
- **Un-block.** Flip `status:` back to `In-progress` and log the resolution.
- **Refine acceptance criteria.** Edit the **Acceptance criteria** section and log the refinement so the history explains the change. If the refinement is large enough to change what "done" means, consider `close` + `new` instead.
### Steps
1. **Read the plan.** `Read('context/plans/NNNN-*.md')`. Confirm it exists and isn't terminal (`Done` / `Abandoned`). Terminal plans should not be edited — log a new plan instead if the work is resuming.
2. **Make the edit(s)** via `Edit` with precise old/new strings. One edit per change; keep diffs small.
3. **Append a Log entry** for anything non-trivial (checking off a single task may skip the log if it's a small step; status changes and new tasks should always log).
4. **Confirm to the user** with a one-line summary of what changed.
## Workflow — `close`
Triggered by:
- `/planner close <NNNN> done "<closing note>"`
- `/planner close <NNNN> abandoned "<reason>"`
### Steps
1. **Read the plan.** Confirm it's not already terminal.
2. **Verify acceptance criteria** (for `done` only). Walk through the Acceptance criteria checklist. If any are unchecked, ask the user explicitly: "criterion X is unmet — close as `done` anyway, or re-scope?" Don't close with false-done signals.
3. **Flip the frontmatter**: `status:` to `Done` or `Abandoned`, `closed:` to today's date.
4. **Append a final Log entry** with the closing note.
5. **Offer an ADR handoff (only on `Done`).** Ask: "did this plan surface a durable architectural decision worth recording as an ADR?" If yes, invoke the `adr` skill with a pre-populated title drawn from the plan's Goal. If no, move on.
6. **Confirm to the user** with the file path and the terminal status. The SessionStart hook will drop the plan from the next session's index automatically.
## What this skill does NOT do
- Does not write Flux manifests — that is `add-flux-app`.
- Does not make architectural decisions — that is `adr`.
- Does not auto-close stale plans. A `review-by` breach is flagged in `list`; the operator still closes manually.
- Does not duplicate cluster state, Renovate state, or git log. Plans reference these sources; they do not mirror them.
- Does not push, commit, or tag — the user owns git operations.
- Does not delete plans. Terminal plans are append-only history.
- Does not replace auto-memory for ephemeral cross-session hints. Memory stays; plans capture the durable "what's next" layer.
## Related skills and agents
- `adr` — hand off here on `close done` if a durable decision emerged. Link the new ADR back from the plan's References section.
- `cluster-intake-gatekeeper` — may hand off to `planner` (as well as `adr`) when an `Add (learning)` verdict comes with a multi-session rollout plan that needs tracking beyond the ADR's own checklist.
- `debug-flux-reconciliation` / `anton-cluster-health` — reactive; a plan is the *forward-looking* companion to these. If a reactive session surfaces follow-up work that spans sessions, open a plan.
## When a plan is NOT warranted
- Single-commit fixes
- Renovate PR triage — use `anton-upgrade-audit` instead; the Renovate dashboard is ground truth
- Read-only investigations with no committed output
- Work that will finish in the current session
- "I'll probably want to do X someday" — not a plan, that's speculation. Revisit when the work is actually starting.
Rule of thumb: *if I walk away for two weeks, would I need this file to pick up where I left off?* If yes, open a plan. If no, skip it.
## Anti-patterns
- **Opening a plan for work that fits in one commit.** Pure overhead. Skip it.
- **Duplicating memory into a plan, or a plan into memory.** Pick one home per piece of state. The plan is canonical for execution state; memory is canonical for ephemeral hints. When in doubt, promote to plan and delete the memory.
- **Editing the Goal to reflect a pivoted scope.** That erases history. `close abandoned` + `new` instead.
- **Leaving a plan `In-progress` for >30 days with no Log entries.** Either the work died (close as abandoned) or it's actually blocked (flip to `Blocked` and name the blocker). Silent drift is the failure mode this system exists to prevent.
- **Letting the active-plan list grow past ~5.** If you have more concurrent initiatives than that, the bottleneck is focus, not tooling.
章节与文件索引
按说明文件中的顺序排列。
为什么存在这个技能
硬性规定
工作流程——新
步骤
工作流程——列表
文件/命令 -> context/plans/NNNN-kebab-slug.md · context/adrs/ · context-repo · close · new · max(existing) + 1 · Draft · In-progress
内容校验值 -> d8a88c2fc265
当前原文的自动摘译,尚未人工审校。
为什么存在这个技能
Anton 已经拥有两个互补的持久层:ADR(
context/adrs/)——不可改变的决定。回答为什么。自动记忆——短暂的跨会话提示。回答我刚刚学到了什么。 Git 日志——不可变的提交。回答发生了什么变化。但缺少一个层面:多会话计划——“采用 Longhorn”、“迁移 Tailscale”、“推出 OpenTelemetry”。这些跨越了许多提交和多个会话。记忆太短暂(随着新条目的推出而衰退); git log 太粗糙(不知道下一步是什么); ADR 过于严格(决策,而非执行状态)。硬性规定
计划是可变的——但要小心。任务列表、日志和状态自由翻转。仅当范围本身发生变化时,目标和验收标准才应更改;重大范围变更应
close该计划已被放弃并且new替代而不是悄悄改变意图。数字永远不会重复使用。下一个号码是max(existing) + 1,用零填充为四位数字。活动状态有Draft,In-progress,Blocked。终端状态有Done,Abandoned。 SessionStart 索引中仅显示活动计划。工作流程——新
触发方式:用户说“为 X 制定计划”/“开始跟踪 X”/
/planner new "<title>"用户想要将运行中的内存条目提升到持久计划中 用户承诺进行多会话迁移、部署或重构 在运行完整的工作流程之前,请问:这真的需要计划吗?如果工作是一次提交、一项 Renovate PR 或将在本次会议中完成的工作,请明确说明并拒绝。计划是针对跨会议的工作。步骤
分配下一个数字。
Glob('context/plans/0[0-9][0-9][0-9]-*.md')。种类。下一个号码是max + 1,补零至 4 位数字。切勿重复使用。生成段头。小写、短横线大小写、删除冠词/介词、4-6 个有意义的单词。示例:“将 Tailscale 迁移到新的 tailnet”→migrate-tailscale-new-tailnet→0001-migrate-tailscale-new-tailnet.md。采访用户。只询问未知的内容:工作流程——列表
触发方式:
/planner list— 默认,仅显示活动计划/planner list --all— 包括终端(完成/放弃)/planner list --status <X>或--affects <X>— 过滤器