Skip to content

Commit 52b70b6

Browse files
Merge pull request #1275 from corbitsdev/cl-9653-tidy-plan-refactor-interview-and-git-worktrees-skills-for
docs(skills): tidy plan, refactor, interview, and worktree guidance
2 parents 94525c6 + f97899d commit 52b70b6

6 files changed

Lines changed: 23 additions & 113 deletions

File tree

‎docs/ARCHITECTURE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -468,7 +468,7 @@ Corbits Code **ships a bundled catalog** as the first-party data-only plugin `pl
468468

469469
`discoverRepoPlugins` locates `plugins/` next to the source root, at `dist/plugins`, or at `dirname(execPath)/plugins`. It never scans the session cwd for the bundled catalog.
470470

471-
Primary is Skywalker. Bundled skill bodies are **how-to playbooks** (steps, done-definition) — not director personas and not fleet routers. Identity and who-does-what live on director system prompts. Default slashes: `/implement`, `/plan`, `/refactor`, `/review`, `/pull-request`, `/issue`, `/docs`, `/interview`. `/review` classifies the target first, then dispatches a selected fleet; `/pull-request` finds or opens the PR for the current branch, and `/review` takes a PR target and reviews it from a worktree; `/docs` is how to maintain PRODUCT / ARCHITECTURE / IMPLEMENTATION; `/implement` takes a plan and a ticket to a pushed branch (worktree, per-commit planner → implement → gate → reviewer loop, whole-branch review, push) and does not steal planning from `/plan`; substantial Builder work consumes a counsel / `/plan` plan first; `/plan` authors an eng change plan and does not implement or file tickets; `/issue` finds or creates the tracker issue — Linear MCP when available, otherwise `ask_operator` for the platform and persists `Preferred issue tracker` in `.corbits/MEMORY.md` There is no first-party dispatch skill — Skywalker orchestrates natively. Draper and emil are closed directors via `spawn_agent(agent=…)`, not slashes. There is no catch-all worker. The operator types the slash; the primary follows the playbook.
471+
The primary is the dispatch director. Bundled skill bodies are **how-to playbooks** (steps, done-definition) — not director personas and not fleet routers. Identity and who-does-what live on director system prompts. Default slashes: `/implement`, `/plan`, `/refactor`, `/review`, `/pull-request`, `/issue`, `/docs`, `/interview`. `/review` classifies the target first, then dispatches a selected fleet; `/pull-request` finds or opens the PR for the current branch, and `/review` takes a PR target and reviews it from a worktree; `/docs` is how to maintain PRODUCT / ARCHITECTURE / IMPLEMENTATION; `/implement` takes a plan and a ticket to a pushed branch (worktree, per-commit planner → implement → gate → reviewer loop, whole-branch review, push) and does not steal planning from `/plan`; substantial coder work consumes a planner / `/plan` plan first; `/plan` authors an eng change plan and does not implement or file tickets; `/issue` finds or creates the tracker issue — Linear MCP when available, otherwise `ask_operator` for the platform and persists `Preferred issue tracker` in `.corbits/MEMORY.md`. There is no first-party dispatch skill: the dispatch director orchestrates natively. Designer and the other specialists are closed directors via `spawn_agent(agent=…)`, not slashes. There is no catch-all worker. The operator types the slash; the primary follows the playbook.
472472

473473
#### Discovery and precedence
474474

‎docs/PRODUCT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ the file path and parse details.
107107

108108
The TUI has an extensible slash-command framework. Built-ins include `/help` (shortcut + command overlay), `/model` (models-only picker for connected accounts; **Alt+A** or `/connect` adds a provider), `/settings`, `/permissions`, `/plugins`, `/clear`, `/new`, `/compact` (fold conversation context now, optional trailing instructions to the summarizer; does not wait for the 60% occupancy governor; idle success shows the fold and does not start a new turn), `/mcp` (enable, disable, or remove servers), `/handoff [optional instructions]` (folds context through the shared operator pipeline, then immediately starts the next turn with the instructions as the inbound content — default copy when omitted; unlike `/compact`, which stops after the fold, handoff always re-infers, so the operator can pivot goals without `/clear`; a handoff issued mid-tool-batch queues behind the in-flight batch and whichever boundary fires first runs the single fold), and `/yolo` (`/yolo [on|off|toggle]`, bare `/yolo` toggles), plus a `/<name>` command per available workflow. `/yolo` persists skip-permissions to the active settings file. That file is the user-global `~/.corbits/settings.json` by default, making the setting machine-wide; explicit `--config <path>` selects a different active file, and `/yolo` writes that file. An ordinary TUI launch without the same `--config` returns to the user-global source and does not modify the custom file. `--dangerously-skip-permissions` and `--yolo` are process-only aliases. Secret-guard and authz still apply. When a session starts with its active persisted setting already on, the TUI and `corbits exec` warn that permission prompts are disabled by saved settings at the active settings path and direct the operator to edit that file to re-enable them. Plugins can register additional commands.
109109

110-
**Default skills** exist out of the gate as first-party slash **actions**, not director names: `/implement`, `/plan`, `/refactor`, `/review`, `/pull-request`, `/issue`, `/docs`, `/interview`. Each one is a how-to playbook — the slash sends the skill body to the primary, which follows the steps. Skills do not assign identity or route the fleet; that stays on director system prompts. `/review` classifies the target first, then dispatches a selected fleet; `/pull-request` finds or opens the PR for the current branch, and `/review` takes a PR target and reviews it from a worktree; `/docs` is how to maintain PRODUCT / ARCHITECTURE / IMPLEMENTATION; `/implement` takes a plan and a ticket to a pushed branch (worktree, per-commit planner/build/reviewer loop, whole-branch review, push, hand off to `/pull-request`) — it does not steal planning from `/plan`. Substantial Builder work consumes a counsel / `/plan` plan first; tiny parent-DIY stays plan-optional. `/plan` authors an eng change plan (files, AC, non-goals, risks, ordered steps) and does not implement. `/issue` finds or creates the tracker issue: Linear MCP when available; otherwise it `ask_operator`s for the platform (GitHub etc.) and persists `Preferred issue tracker` in `.corbits/MEMORY.md` (GitHub via `gh issue create`). There is no first-party dispatch skill — Skywalker orchestrates natively. `typescript` stays `use_skill` only (`user-invocable: false`); `git-worktrees` is a background library that is not listed for `use_skill`. Draper and emil are not slashes; they remain closed directors via `spawn_agent(agent=…)`. There is no catch-all worker. Slash names are also available to the model via `skill_search` (descriptions) then `use_skill` (body). Disable the catalog in `/plugins` (`corbits-skills`) if you want them gone.
110+
**Default skills** exist out of the gate as first-party slash **actions**, not director names: `/implement`, `/plan`, `/refactor`, `/review`, `/pull-request`, `/issue`, `/docs`, `/interview`. Each one is a how-to playbook — the slash sends the skill body to the primary, which follows the steps. Skills do not assign identity or route the fleet; that stays on director system prompts. `/review` classifies the target first, then dispatches a selected fleet; `/pull-request` finds or opens the PR for the current branch, and `/review` takes a PR target and reviews it from a worktree; `/docs` is how to maintain PRODUCT / ARCHITECTURE / IMPLEMENTATION; `/implement` takes a plan and a ticket to a pushed branch (worktree, per-commit planner/build/reviewer loop, whole-branch review, push, hand off to `/pull-request`) — it does not steal planning from `/plan`. Substantial coder work consumes a planner / `/plan` plan first; tiny parent-DIY stays plan-optional. `/plan` authors an eng change plan (files, AC, non-goals, risks, ordered steps) and does not implement. `/issue` finds or creates the tracker issue: Linear MCP when available; otherwise it `ask_operator`s for the platform (GitHub etc.) and persists `Preferred issue tracker` in `.corbits/MEMORY.md` (GitHub via `gh issue create`). There is no first-party dispatch skill: the dispatch director orchestrates natively. `typescript` stays `use_skill` only (`user-invocable: false`); `git-worktrees` is a background library that is not listed for `use_skill`. Designer and the other specialists are not slashes; they remain closed directors via `spawn_agent(agent=…)`. There is no catch-all worker. Slash names are also available to the model via `skill_search` (descriptions) then `use_skill` (body). Disable the catalog in `/plugins` (`corbits-skills`) if you want them gone.
111111

112112
Providers are **models-first**: there is no standalone `/login` command. `/model` opens a **models-only list** (Recent, Favorites, then connected provider/model rows) — type-to-filter owns printable keys, so Connect is never a bare letter. **Alt+A** or `/connect` opens a dedicated add-provider selector over every first-class kind (OpenAI dual-path ChatGPT OAuth or API key, xAI, OpenCode Zen, Anthropic, Google, OpenCode Go, Z.AI Coding Plan, Ollama, Custom), each annotated with its live account count and never filtered out for “already connected.” **Alt+F** toggles favorite on the highlighted model. **Alt+D** persists the highlighted pair as the default without switching the live session. Advanced provider drill-down (edit/delete/tiers) stays on the advanced surface, not a bare printable key while the model list is filtering. OAuth providers open their existing browser login with a named account step so multiple accounts per kind coexist (`codex/work`, …). API-key providers use the same named-instance step before the key (auth-only form: instance name + key + fixed catalog base URL), so personal and team keys land as distinct catalog rows (`openai/default`, `anthropic/work`, …); reusing a name re-keys that instance after confirm. Custom remains a free-form single endpoint (full manual form). Successful connect refreshes the catalog and reopens the model list focused on the new account’s default model. OpenCode Go lists models from the live `/zen/go/v1/models` catalog (packaged seed on fetch failure), routes each by its protocol metadata (chat completions, OpenAI responses, or Anthropic messages) and can show subscription usage in the status bar when active (rolling 5h / weekly / monthly windows when the usage API responds; omitted on auth or network failure). When Go returns a quota or rate-limit error — including some HTTP 400 responses that carry limit payloads — Corbits classifies them so quota aborts cleanly and short provider rate limits remain retryable. On a free-tier or subscription quota hit, wait for the window to reset or use OpenCode Zen free models.
113113

‎plugins/corbits-skills/skills/git-worktrees/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ description: Create and tear down a worktree from origin/<default-branch>. Load
77

88
# git-worktrees
99

10-
Every workflow that writes code or checks out a branch works in a worktree, not the main checkout. Load this with `use_skill("git-worktrees")` and run the commands through `bash`.
10+
Every workflow that writes code or checks out a branch (`/implement`, `/refactor`, and `/review` of a PR) works in a worktree, not the main checkout. Load this with `use_skill("git-worktrees")` and run the commands through `bash`. Tear the worktree down after the PR merges or the change is abandoned.
1111

1212
## Create from origin/<default-branch>
1313

‎plugins/corbits-skills/skills/interview/SKILL.md‎

Lines changed: 15 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -6,128 +6,36 @@ description: Ask the operator batched multiple-choice questions and return the Q
66

77
# Interview
88

9-
Use this skill to gather user input on a topic by asking multiple-choice questions in batches via `ask_operator`. Return the questions and answers in the conversation. The caller decides what to do with them.
10-
11-
This is a utility, not a planner. It does not decide what to build, write any files, or invoke other skills.
9+
Gather input on a topic with multiple-choice questions in batches through `ask_operator`, then return the questions and answers inline. This is a utility: it does not decide what to build, write files, or invoke other skills or agents. The caller decides what to do with the findings.
1210

1311
## Argument
1412

15-
`<topic>[; <context>]`
16-
17-
- **Topic** — what the interview is about
18-
- **Context** (optional) — facts already known. Treat each as an answered dimension; do not re-ask things context settles.
19-
20-
If no topic is given, ask for one before proceeding.
13+
`<topic>[; <context>]`. The topic is what the interview is about. Context is facts already known; treat each as an answered dimension and do not re-ask it. If no topic is given, ask for one first.
2114

2215
## Process
2316

24-
### Identify dimensions to probe
25-
26-
Enumerate the open questions worth asking, drawn from the topic and context. Skip dimensions the context already settles. Add domain-specific ones where relevant. There is no fixed dimension list — the topic determines it.
27-
28-
Probe objective and priorities before details. They shape every later question, so anchoring them early prevents reshuffling halfway through.
29-
30-
### Ask in batches
31-
32-
Each round uses `ask_operator`. Refer to the tool's own documentation for parameter limits and multi-select behavior.
33-
34-
**Quality bar for options:**
17+
1. **Pick dimensions.** List the open questions the topic raises, skipping what the context settles. Probe objective and priorities first, since they shape every later question.
18+
2. **Ask in batches.** 2 to 4 questions per round, bundling independent dimensions. Use one question only when the next one cannot be written without this answer. A later question may reference an earlier answer.
19+
3. **Stop** when every dimension is answered or out of scope, when what remains is detail the caller can decide, when the operator signals fatigue (declines, short non-answers, asks to wrap up), or when the topic has shifted. There is no fixed round cap unless the caller gave one.
3520

36-
- Mutually exclusive and concrete — not "yes / no / maybe"
37-
- Each option a real, defensible choice — not a strawman
38-
- Descriptions surface trade-offs ("simpler but less flexible", "consistent with existing patterns")
39-
- Ground options in the topic and context — do not invent generic options when concrete ones exist
40-
- Multi-select only when the dimension genuinely permits it
41-
- If you have a recommendation, put it first and label it
21+
**Option quality:** concrete and mutually exclusive, each a defensible choice rather than a strawman, with descriptions that surface trade-offs. Ground them in the topic and context. Use multi-select only when the dimension allows it. Put your recommendation first and label it.
4222

43-
**Batching:**
23+
**Trouble:**
4424

45-
- Default 2–4 questions per round, bundling dimensions that do not depend on each other
46-
- Drop to 1 question only when the next question's text or options cannot be authored without this answer
47-
- Referencing a prior answer inside a later question's text is fine
25+
- A contradiction with an earlier answer: ask one question that surfaces both choices, and record the resolution.
26+
- "Other" reveals a missing dimension: add it and continue.
27+
- The answers reframe the topic, or the operator has no objective at all: stop, say what you learned and why you stopped, and let the caller decide.
4828

49-
### Decide when to stop
50-
51-
Stop when:
52-
53-
- Every open dimension has been answered or marked out of scope
54-
- Remaining unknowns are details the caller can reasonably decide
55-
- The user has signalled fatigue (declines to choose, short non-substantive "Other" answers, asks to wrap up)
56-
- The topic has shifted into territory outside this interview's scope
57-
58-
There is no fixed round cap. Stop when the marginal value of another round is low. If the caller passed an explicit cap, honour it.
59-
60-
### Handle trouble
61-
62-
- **Contradiction with a prior answer.** Ask one clarifying question that surfaces both choices directly. Record the resolution; do not silently overwrite.
63-
- **"Other" reveals a missing dimension.** Add it to the dimension list and continue.
64-
- **Topic shift.** If the user's answers reframe the topic itself, stop, emit what you have, and tell the caller the topic has changed.
65-
- **No objective to anchor on.** If the user is fundamentally undecided about the topic's objective itself (not just details), stop without a findings list. Tell the caller what you learned, why you stopped, and what they should consider doing instead.
66-
67-
### Return findings
68-
69-
When the interview ends, emit the Q&A inline as a numbered list of question → answer pairs. Format:
29+
## Return
7030

7131
```
7232
## Interview findings: <topic>
7333
7434
1. <question>: <answer>
75-
2. <question>: <answer>
76-
3. <question>: <answer (multi-select)> — <answer>
35+
2. <question>: <answer (multi-select)> — <answer>
36+
3. <question>: deferred (user said "you decide")
7737
```
7838

79-
If the user declined some questions or punted a dimension, note it in the same list:
80-
81-
```
82-
4. <question>: deferred (user said "you decide")
83-
```
84-
85-
Do not invent a structured summary on top of this. The caller decides what to do with the findings.
86-
87-
After emitting the findings, stop. Do not load other skills, invoke other agents, or write any file.
88-
89-
## Worked example
90-
91-
**Invocation:** `skill(name="interview", arguments="notification system; backend is Node/Postgres, internal users only, must integrate with existing auth")`
92-
93-
**Round 1** (3 questions, bundled because none depends on the others):
94-
95-
```
96-
ask_operator([
97-
{ header: "Goal", question: "What is the primary goal of the notification system?",
98-
options: [
99-
{ label: "Alert on critical events", description: "Errors, security issues, SLA breaches" },
100-
{ label: "Keep users informed of activity", description: "Mentions, replies, updates" },
101-
{ label: "Drive user re-engagement", description: "Digests, reminders, summaries" } ] },
102-
{ header: "Priorities", question: "If you had to pick one, which matters most?",
103-
options: [
104-
{ label: "Reliability of delivery", description: "Never miss a notification, even if delayed" },
105-
{ label: "Latency", description: "Real-time, even if some are dropped under load" },
106-
{ label: "User control", description: "Fine-grained per-event opt-in/out" } ] },
107-
{ header: "Channels", question: "Which delivery channels do you want?", multiSelect: true,
108-
options: [
109-
{ label: "In-app", description: "Notification center in the UI" },
110-
{ label: "Email", description: "Per-event or digest" },
111-
{ label: "Webhook", description: "Outbound HTTP to a user-configured endpoint" } ] }
112-
])
113-
```
114-
115-
**Hypothetical answers:** Alert on critical events; Reliability of delivery; In-app + Email.
116-
117-
**Round 2** builds on round 1 (e.g. email cadence, failure handling). Once no obvious questions remain, emit the findings list and stop.
118-
119-
## Style
120-
121-
- Do not lecture between rounds. A short orientation sentence is fine.
122-
- Do not summarize the user's answers back at them mid-interview.
123-
- Do not ask leading questions.
124-
125-
## Anti-patterns
39+
No summary on top of the list. Then stop: no other skills, no other agents, no files.
12640

127-
- **Interviewing yourself.** Filling in answers because they "seem obvious" — stop and ask, or note as assumption.
128-
- **One question per round, ten rounds deep.** Batch related questions.
129-
- **Asking about everything.** Prune dimensions that do not apply.
130-
- **Treating "Other" as failure.** Custom answers are signal.
131-
- **Forgetting context.** Read it. Do not re-ask things the context already settled.
132-
- **Writing files.** This skill never writes a file. The output is conversational.
133-
- **Invoking other skills or agents.** Emit findings and stop.
41+
Do not lecture between rounds, restate answers mid-interview, ask leading questions, or answer for the operator; note an assumption instead.

0 commit comments

Comments
 (0)