diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9c145a1b6..8fb353472 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -468,7 +468,7 @@ Corbits Code **ships a bundled catalog** as the first-party data-only plugin `pl `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. -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-review`, `/create-issue`, `/docs`, `/interview`. `/review` classifies the target first, then dispatches a selected fleet; `/pull-request-review` is worktree checkout plus a surface pass, loading `/review` for quality rules only; `/docs` is how to maintain PRODUCT / ARCHITECTURE / IMPLEMENTATION; `/implement` is the per-commit greybeard → implement → gate → critic loop 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; `/create-issue` remains the tracker command — 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. +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` is the per-commit greybeard → implement → gate → critic loop 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. #### Discovery and precedence diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md index a91e0c3f6..1bf7acfa1 100644 --- a/docs/PLUGINS.md +++ b/docs/PLUGINS.md @@ -325,7 +325,7 @@ shape. merge into the same `commandPlugin` as `commands/*.md`. Untagged skills still become slashes (marketplace backward compatibility). Frontmatter `argument-hint` is preserved so the TUI can show greyed arg guidance (e.g. - `/create-issue` → `[description] [--from-doc]`). This is an additional + `/issue` → `[description] [--from-doc]`). This is an additional surface: `discoverSkills` skips skills with `disable-model-invocation: true` from the lazy listing (those stay loadable via explicit `use_skill` / `resolveSkillBody`), so the model does not auto-suggest background libraries. diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md index 9eab5cc0d..0bbfb1530 100644 --- a/docs/PRODUCT.md +++ b/docs/PRODUCT.md @@ -20,7 +20,7 @@ That distinction sets priority. **The harness is core and cannot be swapped in later**, because everything runs inside it. Fleet events waking the director, continuous dispatch while capacity is free, unprompted reporting, aggregated health, a bound grounded in real cost rather than a turn count. This is the part no one can hand us and the part a competitor cannot copy from a directory of prompts. -**Agent personas and skills are content.** They define who gets dispatched and to what standard. They are valuable, they are swappable, and they ship as the first-party `corbits-skills` plugin — on by default, disable-able in `/plugins`. The default action set (`/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/docs`, `/interview`) is not an optional install and not something an operator has to discover. +**Agent personas and skills are content.** They define who gets dispatched and to what standard. They are valuable, they are swappable, and they ship as the first-party `corbits-skills` plugin — on by default, disable-able in `/plugins`. The default action set (`/implement`, `/plan`, `/refactor`, `/review`, `/pull-request`, `/issue`, `/docs`, `/interview`) is not an optional install and not something an operator has to discover. **Distribution is packaging for content**, and content is not the constraint. A catalog and an install surface matter eventually; they do not gate anything the product is actually judged on. @@ -107,7 +107,7 @@ the file path and parse details. 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 `/` 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 ` 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. -**Default skills** exist out of the gate as first-party slash **actions**, not director names: `/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-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-review` is worktree checkout plus a surface pass, loading `/review` for quality rules only; `/docs` is how to maintain PRODUCT / ARCHITECTURE / IMPLEMENTATION; `/implement` is the per-commit review/build/critique loop — 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. `/create-issue` remains the tracker command: 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. `linear-issue-workflow`, `style`, `philosophy`, `native-integration`, and `typescript` stay `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. +**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` is the per-commit review/build/critique loop — 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. `linear-issue-workflow`, `style`, `philosophy`, `native-integration`, and `typescript` stay `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. 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. @@ -155,7 +155,7 @@ Capabilities beyond the core toolset are opt-in plugins, enabled per workspace t ## Multi-agent (fleet agents) -The primary session is always **orchestrator** (single-agent mode is gone). Its identity is **Skywalker** (product name remains Corbits Code; when asked its name, answer Skywalker): classify work, DIY tiny/single-file/one-route product edits, dispatch a **closed fleet of 20 directors** for substantial work, track the fleet, and synthesize. Product mutation tools (`write_file` / `edit_file` / `delete_file`) are mounted on the primary (CORE / `SKYWALKER_TOOLS`) — path tools are the DIY surface; spawn remains the default for substantial, multi-file, parallel, or specialist work. Shell file-writes stay denied. MCP tools are not re-filtered by a product-write deny list (that list is gone). There is no static per-package write-path declaration (CL-6952 removed it — no shipped director ever set one). A concurrent dispatch landing on the same working directory as another still-running lane is recorded as a `conflict` intervention, not blocked. Operator slash recipes (`/implement`, `/plan`, `/refactor`, `/review`, `/pull-request-review`, `/create-issue`, `/docs`, `/interview`) tell Skywalker which directors to spawn for substantial work (`/lexicon` runs on the primary and spawns nothing); tiny/bounded edits may run on the primary. +The primary session is always **orchestrator** (single-agent mode is gone). Its identity is **Skywalker** (product name remains Corbits Code; when asked its name, answer Skywalker): classify work, DIY tiny/single-file/one-route product edits, dispatch a **closed fleet of 20 directors** for substantial work, track the fleet, and synthesize. Product mutation tools (`write_file` / `edit_file` / `delete_file`) are mounted on the primary (CORE / `SKYWALKER_TOOLS`) — path tools are the DIY surface; spawn remains the default for substantial, multi-file, parallel, or specialist work. Shell file-writes stay denied. MCP tools are not re-filtered by a product-write deny list (that list is gone). There is no static per-package write-path declaration (CL-6952 removed it — no shipped director ever set one). A concurrent dispatch landing on the same working directory as another still-running lane is recorded as a `conflict` intervention, not blocked. Operator slash recipes (`/implement`, `/plan`, `/refactor`, `/review`, `/pull-request`, `/issue`, `/docs`, `/interview`) tell Skywalker which directors to spawn for substantial work (`/lexicon` runs on the primary and spawns nothing); tiny/bounded edits may run on the primary. | Lane | Directors | | --------- | -------------------------------------------------------------------------------------------------------- | diff --git a/plugins/corbits-skills/manifest.json b/plugins/corbits-skills/manifest.json index befe1b3d0..323880d39 100644 --- a/plugins/corbits-skills/manifest.json +++ b/plugins/corbits-skills/manifest.json @@ -3,5 +3,5 @@ "name": "Corbits Skills", "kind": "command", "defaultEnabled": true, - "description": "Default operator skills and slash commands (implement, refactor, review, pull-request-review, create-issue, docs, interview, plan)." + "description": "Default operator skills and slash commands (implement, refactor, review, pull-request, issue, docs, interview, plan)." } diff --git a/plugins/corbits-skills/skills/create-issue/SKILL.md b/plugins/corbits-skills/skills/create-issue/SKILL.md deleted file mode 100644 index 5aa38c6b5..000000000 --- a/plugins/corbits-skills/skills/create-issue/SKILL.md +++ /dev/null @@ -1,477 +0,0 @@ ---- -name: create-issue -description: Create a structured issue in Linear, GitHub, or GitLab. -argument-hint: "[description] [--from-doc]" ---- - -# Create Issue - -Use this skill to create properly structured issues. On Linear, also projects, project updates, and/or initiatives when the operator asks. Tracker selection first, then the quality phases, then create. - -Clarifying questions use `ask_operator`. Do not invent Claude-only tools. Do not invent a Linear REST client. Do not restate MCP tool names or schemas — use the mounted Linear MCP tools as they appear in the toolset. - -## Tracker selection - -Pick the tracker before drafting. Do not skip this. - -1. If `mcp__linear__*` tools are available → **Linear**. Do not ask. -2. Else `read_file` `.corbits/MEMORY.md` for `Preferred issue tracker:`. If present, use that tracker. -3. Else `ask_operator` with options: GitHub / GitLab / Linear (enable MCP) / Other. Persist the choice: append `Preferred issue tracker: ` to `.corbits/MEMORY.md` only (write_file/edit_file — path tools are the DIY surface; shell writes stay denied). -4. **GitHub** → `gh issue create` (title + body) via `run_shell`. If `gh` is missing, tell the operator to install GitHub CLI and stop. Do not invent an HTTP client. -5. **GitLab** → `glab issue create` (title + body) via `run_shell`. If `glab` is missing, tell the operator and stop. -6. **Linear without MCP** → stop. Tell the operator to enable Linear MCP. Do not invent a Linear REST client. -7. **Other** → `ask_operator` how they file issues, then follow that. - -## Phase 1: Document Discovery - -When the operator provides `--from-doc` or mentions a planning document, search for `/docs`-managed documents: - -1. Look for `PRODUCT.md`, `ARCHITECTURE.md`, `IMPLEMENTATION.md` in: - - Repository root - - `docs/` directory - -2. If no documents are found, `ask_operator`: - > I couldn't find any planning documents. Do you have a document you'd like me to reference? - -3. When a document is found, read it and extract: - - Features or work items mentioned - - Technical context and constraints - - Scope indicators (timeline mentions, complexity signals) - -Use extracted information to: - -- Pre-populate issue descriptions with relevant context -- Propose appropriate artifact types based on scope -- Ask targeted follow-up questions for gaps not covered by the document - -## Phase 2: Analyze Input - -Determine what the operator wants to create: - -1. **Explicit request**: Operator specifies artifact type ("create an issue for...", "create a project for...", "post a project update for...") -2. **From document**: Operator provides `--from-doc` to extract work items from planning documents -3. **Freeform**: Operator describes work without specifying type - -Project updates are a distinct artifact: they communicate status on an existing project to a non-technical audience and are never inferred from scope. The operator must explicitly ask for one. Skip project / initiative / update artifacts on GitHub and GitLab unless the operator wants an issue-shaped stand-in. - -For freeform input, estimate the scope: - -| Scope | Duration | Artifact | -| ------ | --------- | --------------------------------------------------------------------- | -| Small | 1-3 days | Single issue | -| Medium | 1-2 weeks | Project with issues (Linear) or a set of issues (GitHub / GitLab) | -| Large | Quarter+ | Initiative with projects (Linear) or grouped issues (GitHub / GitLab) | - -Present your assessment to the operator and confirm before proceeding. - -## Phase 3: Interview - -If information is missing, ask targeted questions. Keep interviews brief and focused. - -### For Issues - -Required information: - -- What problem does this solve or what value does it add? -- How will we know it's done? (acceptance criteria) - -Optional: - -- Are there technical constraints or dependencies? -- Which team should own this? - -### For Projects (Linear) - -Required information: - -- What is the goal/outcome of this project? -- What is the target timeframe? -- Who should lead this project? - -Optional: - -- What teams are involved? -- What are the key milestones? - -### For Initiatives (Linear) - -Required information: - -- What strategic objective does this serve? -- Who is the executive owner? -- What projects should be included? - -### For Project Updates (Linear) - -Required information: - -- Which project is this update for? Confirm with the operator if the match is not exact. -- What is the project's current health? (on track, at risk, off track, completed, paused) -- What has the project unlocked or enabled since the last update? Describe in terms of capabilities, outcomes, or things that are now possible — not lists of completed tickets. -- What's coming next, framed by user-visible impact? -- Are there any risks or blockers the audience needs to know about? Describe them by impact, not implementation. - -Optional: - -- Should the update be tied to a specific milestone? - -Before drafting, retrieve the most recent prior update so the new one continues the narrative rather than restating prior progress. - -## Phase 4: Draft Content - -Create drafts following these conventions: - -### Do Not Reference Local Files - -Tracker artifacts are read by people who do not share your working directory. Do not include local file paths, line numbers, working-tree-relative paths, or instructions like "see `src/foo.ts`" in titles, descriptions, or comments. Those references rot, are not clickable, and assume context the reader does not have. - -Instead: - -- Describe the behavior, module, or concept in plain language ("the authentication middleware", "the request retry logic") -- Link to permanent URLs (GitHub permalinks at a specific commit, published documentation) when a precise pointer is required -- Quote the relevant code inline if a short excerpt is needed for context - -This applies equally when drafting from planning documents — extract the meaning, do not transcribe paths. - -### Specs Belong as Attachments - -If a spec, design document, or planning artifact needs to be preserved so an implementer can refer to it, attach it to the Linear artifact rather than referencing the local file path: - -- Specs that describe an entire project's scope or design attach to the **project** -- Specs that describe a single unit of work attach to the **issue** for that work - -On Linear, upload with the mounted Linear MCP tools. Once attached, any reference inside the issue or project description should point to the attached document — never to the original local file path. On GitHub / GitLab, paste meaning into the body or link a permanent URL. - -### Issue Format - -**Title**: Clear and actionable. Verb phrases are preferred, but sentences or noun phrases are acceptable when they provide clarity. - -- Good: "Add retry logic for failed API calls" -- Good: "Fix race condition in transaction verification" -- Good: "Create market validation track for " -- Bad: "API retry" (too vague) -- Bad: "Bug in transactions" (not actionable) - -**Description**: - -``` -# Background - - - -# Outcome - - - -- [ ] -- [ ] -``` - -For simple tasks, you can omit `# Background` and use only `# Outcome` with checkboxes. - -**Labels and Priority**: - -- Set priority based on urgency and impact -- Apply labels for categorization (e.g., bug, feature, tech-debt) if the workspace uses them -- `ask_operator` about priority and labels if not specified - -When appropriate, use subsections under `# Outcome` to organize related items: - -``` -# Outcome - -## Questions - -- [ ] What are the key takeaways? -- [ ] Which parts apply to our strategy? - -## Tasks - -- [ ] Document findings -- [ ] Present to team -``` - -### Project Format (Linear) - -**Name**: Outcome-focused description - -- Good: "User authentication with SSO support" -- Good: "Get 10 customer leads for through direct outreach" -- Bad: "Auth work" - -**Description**: Goal, scope, and any constraints. - -For validation or experiment projects, use the Hypothesis/Experiment/Steps pattern: - -``` -Hypothesis - - -Experiment - - -* -* -* -``` - -**Milestones**: Key checkpoints showing progression toward the goal. Examples: - -- Completion states: "Target list ready", "Outreach completed", "Analysis complete" -- Phase labels: "MVP", "Full implementation", "Polish and launch" - -### Initiative Format (Linear) - -**Name**: Strategic objective - -**Description**: Include as much information as needed to convey the business goal and how success will be measured. If unsure what to include, prompt the operator for guidance. - -### Project Update Format (Linear) - -**Audience**: Project updates are read by non-technical stakeholders — founders, GMs, customer-facing teammates, leadership, and sometimes customers. Write for someone who cares about *what the project makes possible*, not *what work was done*. - -**Style rules:** - -- Lead with what is now possible, available, or unblocked because of recent progress. The reader wants to know what changed for them, not what changed in the codebase. -- Do not enumerate completed issues, PR titles, commits, or internal implementation details. "Shipped INF-204, INF-205, INF-211" is the wrong shape; "Customers can now invite teammates and assign roles without contacting support" is the right shape. -- Avoid jargon, acronyms, internal codenames, and tool-of-the-week terminology unless they are already part of the audience's vocabulary. When in doubt, spell it out in plain language. -- Frame risks and blockers by their impact on the outcome ("the launch date may slip by two weeks because we are still waiting on the vendor's API access"), not by their technical cause. -- Keep it short. A project update that takes more than a minute to read will not be read. - -**Structure**: - -``` -## Where we are - - - -## What this unlocks - - - -## What's next - - - -## Risks - - -``` - -If a section has nothing meaningful to say in this update, omit it rather than padding it. - -**Health**: Set the project health to match reality (`onTrack`, `atRisk`, `offTrack`, `complete`, or `paused`). If you would not show the chosen health to the project's sponsor with a straight face, it is the wrong health. - -**Self-check before posting**: Re-read the draft and ask, "would a non-engineer who has never opened the codebase come away knowing what changed for them?" If the answer is no, rewrite it. - -## Phase 5: Review and Adjust - -Present the complete draft to the operator: - -``` -I propose creating: - -**Project**: Add user authentication -- Lead: -- Target: -- Milestones: - 1. Basic auth flow complete - 2. SSO integration complete - -**Issues**: -1. "Set up authentication database schema" -2. "Implement login/logout flow" -3. "Integrate SSO provider" -4. "Add session management" - - Blocked by: #2 - -Would you like to adjust anything before I create these? -``` - -Allow the operator to: - -- Adjust titles or descriptions -- Change the structure (e.g., "make #3 and #4 one issue") -- Add or remove items -- Specify assignees or teams - -`ask_operator` whether to adjust before creating. - -## Phase 6: Create - -### Linear - -Before creating artifacts, discover workspace context (teams, and projects/initiatives when linking) with the mounted Linear MCP tools (`mcp__linear__*` family only — do not restate individual tool names or schemas). `ask_operator` when multiple choices exist. - -After approval: create containers first, then issues in dependency order (status **Todo** unless the operator says otherwise), then relationships / project / initiative links, then project updates. Report URLs. Do not invent a Linear REST client. - -### GitHub - -```bash -gh issue create --title "" --body "<body>" -``` - -Report URLs. Missing `gh` → tell the operator and stop. - -### GitLab - -```bash -glab issue create --title "<title>" --description "<body>" -``` - -Report URLs. Missing `glab` → tell the operator and stop. - -### Linear without MCP / Other - -Stop for Linear-without-MCP (enable MCP). For Other, follow the operator's filing recipe. - -## Error Handling - -If creation fails: - -1. Report the error with any details provided -2. List what was successfully created before the failure (with URLs if available) -3. Do not proceed with dependent artifacts if a parent fails (e.g., don't create issues if project creation failed) -4. Ask if they want to retry or adjust the request - -## Quality Reminders - -- Issues should be self-contained and handoff-ready at any moment -- A single issue should take no more than 2-3 days to implement -- Use many tickets if needed for clarity; they're cheap -- Status updates in tickets reduce interruptions - -If an issue looks like it will take more than 3 days, suggest breaking it down. - -## Common Patterns - -### Bug Report to Issue - -``` -User: "The login page crashes when you enter special characters" - -Issue: - Title: Fix login page crash on special character input - Description: - # Background - - Login page crashes when users enter special characters in the - username or password field. - - Steps to reproduce: - 1. Navigate to /login - 2. Enter "user@test" in username - 3. Page crashes - - # Outcome - - - [ ] Special characters in username field do not cause crash - - [ ] Special characters in password field do not cause crash - - [ ] Input is properly sanitized before processing -``` - -### Feature Request to Project and Issues - -``` -User: "We need to add dark mode to the application" - -Project: Add dark mode theme support - Target: 2 weeks - Milestones: - 1. Theme infrastructure complete - 2. All components themed - -Issues: - 1. "Add theme context and toggle component" - 2. "Define dark mode color palette" - 3. "Update core components for theme support" - - Blocked by: #1, #2 - 4. "Add theme persistence to user preferences" - - Blocked by: #1 -``` - -### Validation Project - -``` -User: "We need to validate if customers want our new <product-name> product" - -Project: Get 10 customer leads for <product-name> through direct outreach - Lead: <to be assigned> - Target: 2 weeks - Description: - Hypothesis - Teams we know and can reach out to have a need for <product-name>. - - Experiment - Direct Outreach - - - [ ] Create list of targets - - [ ] Create collateral if needed - - [ ] Create strategy for outreach including any templates - - [ ] Execute outreach - - [ ] Conduct customer interviews - - [ ] Analyze results - - Milestones: - 1. Target list and collateral ready - 2. Outreach completed - 3. Customer interviews recorded - 4. Analysis complete - -Issues: - 1. "Create target list for <product-name> outreach" - 2. "Create outreach collateral and templates" - 3. "Execute outreach campaign" - - Blocked by: #1, #2 - 4. "Conduct and record customer interviews" - - Blocked by: #3 - 5. "Analyze results and present findings" - - Blocked by: #4 -``` - -### Strategic Goal to Initiative - -``` -User: "We need to expand our platform to support enterprise customers" - -Initiative: Enterprise platform expansion - Owner: <executive-owner> - Target: <target-quarter> - -Projects: - 1. "Multi-tenant architecture" - Isolate customer data and resources - 2. "Enterprise SSO integration" - Support SAML and OIDC providers - 3. "Admin dashboard" - Self-service management for enterprise admins - 4. "Audit logging" - Compliance-ready activity tracking -``` - -### Planning Document to Issues - -``` -User: "Create issues from our product doc" or "--from-doc" - -[Skill searches for PRODUCT.md, ARCHITECTURE.md, IMPLEMENTATION.md] -[Finds PRODUCT.md with feature descriptions] - -Skill: I found PRODUCT.md which describes the following features: - - User authentication with SSO - - Usage metrics dashboard - - Export functionality - -Based on the document, I propose: - -**Project**: User authentication with SSO support - (From PRODUCT.md: "Users need secure login with enterprise SSO...") - -**Issues**: - 1. "Implement basic email/password authentication" - # Background - From PRODUCT.md: Users need secure login... - - # Outcome - - [ ] Users can register with email/password - - [ ] Users can log in and log out - - 2. "Integrate SAML SSO provider" - ... - -Which features would you like me to create issues for? -``` diff --git a/plugins/corbits-skills/skills/issue/SKILL.md b/plugins/corbits-skills/skills/issue/SKILL.md new file mode 100644 index 000000000..db8808255 --- /dev/null +++ b/plugins/corbits-skills/skills/issue/SKILL.md @@ -0,0 +1,47 @@ +--- +name: issue +description: Find or create the issue for this work in Linear, GitHub, or GitLab. +argument-hint: "[description] [--from-doc]" +--- + +# Issue + +Check whether the work already has an issue. If it does, report it. If not, draft one and create it. + +Ask with `ask_operator`. Use the mounted tracker tools as they appear in the toolset; do not restate their names or schemas, and do not invent a REST client. + +## 1. Pick the tracker + +1. Linear MCP tools mounted: Linear. Do not ask. +2. Else read `.corbits/MEMORY.md` for `Preferred issue tracker:` and use it. +3. Else ask: GitHub, GitLab, Linear (enable MCP), or other. Save the answer as `Preferred issue tracker: <name>` in `.corbits/MEMORY.md`, never secrets. +4. GitHub uses `gh`, GitLab uses `glab`, both through `bash`. If the CLI is missing, tell the operator and stop. Linear without MCP: tell the operator to enable it and stop. + +## 2. Look for an existing issue + +Search the tracker for the ticket id in the branch name, then for the description's key terms. If a match covers the work, show it and stop. If it is close but incomplete, ask whether to update it or file a new one. + +## 3. Draft + +With `--from-doc` or a named planning document, read it (`PRODUCT.md`, `ARCHITECTURE.md`, `IMPLEMENTATION.md`, a `/plan` output) and draft from it. Otherwise draft from the operator's description and what the repo shows. Ask only for what you cannot infer. + +**Title:** a clear, actionable phrase ("Add retry logic for failed API calls", not "API retry"). + +**Description:** + +``` +# Background + +Why this matters and the current state. Include reproduction steps for a bug. + +# Outcome + +- [ ] Observable, verifiable result +- [ ] Another result +``` + +Split work that is really several independent outcomes into separate issues, and on Linear group them under a project when the operator asks for one. Scope one issue to one reviewable PR. + +## 4. Create + +Create the issue and report its id and URL. On Linear, attach planning documents to the issue (or project for whole-project specs) and point descriptions at the attachment, not a local path. On GitHub or GitLab, paste the meaning into the body or link a permanent URL. diff --git a/plugins/corbits-skills/skills/native-integration/SKILL.md b/plugins/corbits-skills/skills/native-integration/SKILL.md index 21e9456ce..2bfcf4f91 100644 --- a/plugins/corbits-skills/skills/native-integration/SKILL.md +++ b/plugins/corbits-skills/skills/native-integration/SKILL.md @@ -28,11 +28,11 @@ Move the issue to In Review when the PR is ready for review. Draft or WIP PRs st ## Non-git folders -A folder without `.git` is a valid working directory (scratch, unpacked tarball, new project). Git-using skills (`implement`, `review`, `pull-request-review`) no-op or ask when they need a repo. Do not invent a git repo to satisfy them. +A folder without `.git` is a valid working directory (scratch, unpacked tarball, new project). Git-using skills (`implement`, `review`, `pull-request`) no-op or ask when they need a repo. Do not invent a git repo to satisfy them. ## Tracker-agnostic issues -`/create-issue` is not Linear-only: +`/issue` is not Linear-only: 1. Linear MCP available: Linear. 2. Else ask which tracker (GitHub, GitLab, other) unless `.corbits/MEMORY.md` already has `Preferred issue tracker`. @@ -51,7 +51,7 @@ This step is the delivery of the review, not a second pass of analysis. By the t Post when any of these is true: -- The user asked for a PR review (`pull-request-review`, a PR URL, or an explicit "review #N") +- The user asked for a PR review (a PR URL or an explicit "review #N") - `linear-issue-workflow` Phase 5 self-review has cleared and Phase 6 is opening or updating the PR - An open PR exists for the branch and the review's purpose is to leave a record on it diff --git a/plugins/corbits-skills/skills/plan/SKILL.md b/plugins/corbits-skills/skills/plan/SKILL.md index 52239df8a..dfd430a70 100644 --- a/plugins/corbits-skills/skills/plan/SKILL.md +++ b/plugins/corbits-skills/skills/plan/SKILL.md @@ -21,6 +21,6 @@ When requirements are fuzzy, put open questions under Blockers instead of invent ## What this is not -- Not `/create-issue`. If the operator wants tickets, they use `/create-issue` after the plan. +- Not `/issue`. If the operator wants tickets, they use `/issue` after the plan. - Not an architecture gate. Planner reviews approach; this skill only authors the plan. - Not implementation. Do not ship the change. diff --git a/plugins/corbits-skills/skills/pull-request-review/SKILL.md b/plugins/corbits-skills/skills/pull-request-review/SKILL.md deleted file mode 100644 index 65efc7328..000000000 --- a/plugins/corbits-skills/skills/pull-request-review/SKILL.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -name: pull-request-review -description: Review a pull request by branch or URL in a git worktree. ---- - -# Pull Request Review - -Use this skill to review a pull request given a branch name or URL. - -## Input Formats - -This skill accepts either: - -- A branch name (e.g., `feature/add-auth`) -- A pull request URL from GitHub or GitLab (e.g., `https://github.com/owner/repo/pull/123`) - -## Workflow - -### Step 1: Parse Input - -If given a URL, extract the pull request information: - -```bash -# GitHub PR URL format: https://github.com/owner/repo/pull/123 -# GitLab MR URL format: https://gitlab.com/owner/repo/-/merge_requests/123 - -# For GitHub, use gh CLI to get branch name -gh pr view <url-or-number> --json headRefName --jq '.headRefName' - -# For GitLab, use glab CLI or parse the MR page -glab mr view <number> --output json | jq -r '.source_branch' -``` - -### Step 2: Determine Repository Root - -Find the root of the current git repository: - -```bash -git rev-parse --show-toplevel -``` - -### Step 3: Fetch and Verify the Branch - -Fetch the branch from the remote and verify it exists: - -```bash -# Fetch the specific branch -git fetch origin <branch-name> - -# Verify the branch exists -if ! git rev-parse --verify "origin/<branch-name>" >/dev/null 2>&1; then - echo "Error: Branch '<branch-name>' does not exist on the remote." - exit 1 -fi -``` - -If the branch does not exist, inform the user of the error and stop. Do not proceed with worktree creation or review. - -### Step 4: Create Worktree - -Create a worktree in a sibling directory under `worktree/`: - -```bash -# From repository root -REPO_ROOT=$(git rev-parse --show-toplevel) -WORKTREE_PATH="${REPO_ROOT}/../worktree/<branch-name>" - -# Create the worktree directory if needed -mkdir -p "${REPO_ROOT}/../worktree" - -# Add the worktree -git worktree add "$WORKTREE_PATH" "origin/<branch-name>" -``` - -The worktree path follows the pattern `../worktree/<branch-name>` relative to the repository root. - -### Step 5: Change to Worktree and Checkout Branch - -Change the working directory to the new worktree and ensure the branch is checked out: - -```bash -cd "$WORKTREE_PATH" - -# Checkout the branch -git checkout <branch-name> - -# Verify you are on the correct branch -git branch --show-current -``` - -Confirm the output matches the expected branch name before proceeding. - -### Step 6: Set Up the Repository - -Before reviewing, the repository must be properly set up. Look for developer documentation that describes how to install dependencies and prepare the codebase: - -1. Search for setup instructions in these common locations: - - `README.md` - - `CONTRIBUTING.md` - - `docs/` directory - - `DEVELOPMENT.md` - - `SETUP.md` - -2. Follow the documented setup steps exactly. Common setup tasks include: - - Installing dependencies (`npm install`, `yarn`, `pip install`, `bundle install`, etc.) - - Setting up environment variables - - Running database migrations - - Building assets or compiling code - -3. Do not assume the setup process. Every repository has its own conventions and requirements. - -4. If no setup documentation exists, ask the user how to set up the repository before proceeding. - -### Step 7: Determine Base Branch - -Identify the base branch for comparison: - -```bash -# For GitHub PRs -gh pr view --json baseRefName --jq '.baseRefName' - -# For GitLab MRs -glab mr view --output json | jq -r '.target_branch' - -# If working from branch name only, assume main or master -git branch -r | grep -E 'origin/(main|master)$' | head -1 | sed 's/.*origin\///' -``` - -### Step 8: Load Review Quality Rules Only - -Load the `review` skill for quality rules only — signal over noise, -cite the check, comment tone and body. Skip its classify and fleet -dispatch: this skill already owns the target (this PR) and the fleet -(the surface pass below). - -### Step 9: Surface Pass - -Run a surface pass on the diff: Reviewer on the diff plus at most one -extra lens. Do not dispatch a wider fleet. - -### Step 10: Post the Review on GitHub - -Post the findings on the pull request: - -```bash -# For GitHub PRs -gh pr review <number> --comment --body "<review body>" - -# Or leave a plain comment -gh pr comment <number> --body "<review body>" -``` - -## Cleanup - -After the review is complete, the worktree can be removed: - -```bash -git worktree remove "$WORKTREE_PATH" -``` - -Inform the user that the worktree remains available for further investigation and can be removed manually when no longer needed. - -## Error Handling - -If any command fails during the workflow, do not retry or attempt workarounds. Stop immediately and ask the user for guidance. Common failure scenarios include: - -- Branch does not exist remotely -- Worktree creation fails -- Checkout fails -- Setup commands fail -- CLI tools (gh, glab) are not available or not authenticated - -Present the error output to the user and ask how they would like to proceed. diff --git a/plugins/corbits-skills/skills/pull-request/SKILL.md b/plugins/corbits-skills/skills/pull-request/SKILL.md new file mode 100644 index 000000000..7b07551de --- /dev/null +++ b/plugins/corbits-skills/skills/pull-request/SKILL.md @@ -0,0 +1,52 @@ +--- +name: pull-request +description: Find or open the pull request for the current branch. +argument-hint: "[--draft]" +--- + +# Pull request + +Check whether the current branch already has a PR. If it does, report it. If not, open one. + +Requires a git repo and a branch other than the default branch. Stop and say so otherwise. + +## 1. Look for an existing PR + +```bash +gh pr view --json url,state,isDraft,baseRefName +``` + +If an open PR exists, report its URL, state, and base, offer to refresh the title or body if the branch has changed, and stop. On GitLab use `glab mr view`. + +## 2. Prepare the branch + +- Working tree clean, or ask what to do with the changes. +- Branch pushed to the remote: `bin/git-push-scoped origin <branch>` when the repo has it, else `git push -u origin <branch>`. Never force-push a published branch. +- A ticket exists for the work. If none, run `/issue` first. +- For a stacked branch, base on the previous branch, not the default branch. + +## 3. Write the PR + +Read `CONTRIBUTING.md` and follow its title and body rules. Describe the whole branch, not its latest commit: + +```markdown +## Summary + +- What changed and why, present tense. + +## Verification + +- The checks you ran and what they showed. + +Fixes <ticket> +``` + +Use `--draft` for work in progress. + +## 4. Open and report + +```bash +gh pr create --base <base> --head <branch> --title "<title>" --body-file <file> +``` + +Report the URL. When the PR is ready for review (not draft), set a tracked Linear issue to In Review. Draft or WIP PRs keep the issue In Progress. Never mark the issue Done on open. diff --git a/plugins/corbits-skills/skills/review/SKILL.md b/plugins/corbits-skills/skills/review/SKILL.md index 239e10bc3..7b2a52d99 100644 --- a/plugins/corbits-skills/skills/review/SKILL.md +++ b/plugins/corbits-skills/skills/review/SKILL.md @@ -28,7 +28,14 @@ Then the primary dispatches the warranted lenses with `spawn_agent`, one target - Designer or Warden only when the touched files warrant that lens (UI surface, or security-sensitive code). -When the target is a PR, read the PR tree from the worktree — worktree checkout belongs to `/pull-request-review`; never review the local checkout as a stand-in for the PR. +When the target is a PR (number, URL, or branch), review it from a worktree, never from the local checkout: + +1. Resolve the PR and its head branch with `gh pr view <ref> --json headRefName,baseRefName,number,url`. Stop and ask if it does not exist. +2. `git fetch origin <head-branch>`, then create a worktree for it with `use_skill("git-worktrees")`. +3. Review there. Use the PR's base as the diff base. +4. Post the finished review on the PR (see the GitHub posting rules), then remove the worktree. + +If any step fails, stop and ask instead of working around it. ## Base Branch Determination diff --git a/src/telemetry/classify.ts b/src/telemetry/classify.ts index 757e66fa1..e2befdfc1 100644 --- a/src/telemetry/classify.ts +++ b/src/telemetry/classify.ts @@ -83,15 +83,15 @@ const BUILT_IN_AGENT_NAMES: ReadonlySet<string> = new Set([ // never a leak). Project- or plugin-authored skills are never reported by // name. const FIRST_PARTY_SKILL_NAMES: ReadonlySet<string> = new Set([ - "create-issue", "docs", "git-worktrees", "implement", "interview", + "issue", "linear-issue-workflow", "philosophy", "plan", - "pull-request-review", + "pull-request", "refactor", "review", "style",