From 12ea4f7eb13aea48b21c63ab9a1fe66925b1479b Mon Sep 17 00:00:00 2001 From: Dominik Simonik Date: Mon, 21 Sep 2026 15:17:19 +0200 Subject: [PATCH 1/2] refactor: prep skills and agents for claude 5gen models Apply the Claude 5-generation context-engineering rules: progressive disclosure over upfront detail, a single source per instruction, and expressive descriptions instead of worked examples. - Strip blocks from six agent descriptions and rewrite them to route on their own. Those blocks were concatenated into every request, costing ~2,400 tokens per turn for agents dispatched by name anyway. - Merge when_to_use into description so the trigger surface has one source. - Extract the procedures duplicated across skills into shared references: feature-branch.md (brainstorm, plan, debrief) and review-dispatch.md (build, hotfix, review). - Demote run-time detail out of SKILL.md bodies: commit-autonomy.md and ship-gate.md (build), plan-authoring.md (plan), issue-previews.md (debrief). - Drop trailing Important / Key Principles blocks that restated the body, moving each load-bearing line to the step it governs. - Document the KEEP / DEMOTE / DELETE rubric and the agent-description rule in CONTRIBUTING.md, with a pointer from AGENTS.md. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 27 +++++- CONTRIBUTING.md | 67 +++++++++++++-- agents/analysis/plan-splitting-agent.md | 30 +------ .../code-simplicity-review-agent.md | 30 +------ .../codebase-review/codebase-review-agent.md | 30 +------ agents/codebase-review/vgv-review-agent.md | 38 +-------- .../architecture-review-agent.md | 30 +------ .../test-quality-review-agent.md | 30 +------ skills/brainstorm/SKILL.md | 45 +++------- .../brainstorm/references/feature-branch.md | 1 + skills/build/SKILL.md | 84 ++----------------- skills/build/references/commit-autonomy.md | 50 +++++++++++ skills/build/references/review-dispatch.md | 1 + skills/build/references/ship-gate.md | 17 ++++ skills/create-pr/SKILL.md | 3 +- skills/create/SKILL.md | 10 +-- skills/debrief/SKILL.md | 48 ++--------- skills/debrief/references/feature-branch.md | 1 + skills/debrief/references/issue-previews.md | 40 +++++++++ skills/elements-of-style/SKILL.md | 3 +- skills/hotfix/SKILL.md | 20 +---- skills/hotfix/references/review-dispatch.md | 1 + skills/plan-technical-review/SKILL.md | 3 +- skills/plan/SKILL.md | 78 ++++------------- skills/plan/references/feature-branch.md | 1 + skills/plan/references/plan-authoring.md | 38 +++++++++ skills/rebase/SKILL.md | 10 +-- skills/refine-approach/SKILL.md | 15 ++-- skills/review/SKILL.md | 38 ++------- skills/review/references/review-dispatch.md | 1 + skills/shared/references/feature-branch.md | 14 ++++ skills/shared/references/review-dispatch.md | 27 ++++++ 32 files changed, 348 insertions(+), 483 deletions(-) create mode 120000 skills/brainstorm/references/feature-branch.md create mode 100644 skills/build/references/commit-autonomy.md create mode 120000 skills/build/references/review-dispatch.md create mode 100644 skills/build/references/ship-gate.md create mode 120000 skills/debrief/references/feature-branch.md create mode 100644 skills/debrief/references/issue-previews.md create mode 120000 skills/hotfix/references/review-dispatch.md create mode 120000 skills/plan/references/feature-branch.md create mode 100644 skills/plan/references/plan-authoring.md create mode 120000 skills/review/references/review-dispatch.md create mode 100644 skills/shared/references/feature-branch.md create mode 100644 skills/shared/references/review-dispatch.md diff --git a/AGENTS.md b/AGENTS.md index a7e15f5..635aeba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,11 +51,34 @@ skills/ # User-invocable and supporting skills (one dir per skill rebase/SKILL.md # Sync a feature branch with its base elements-of-style/SKILL.md # Apply Strunk's Elements of Style to prose shared/ # Shared references and scripts used across skills - references/ # Plan templates, review procedures, handoff steps + references/ + clear-context-handoff.md # The "clear context and " handoff block + drive-to-green.md # Loop until every gate is green by real output + feature-branch.md # Branch check run before anything is written to disk + file-findings-on-pr.md # Post review findings as PR comments + plan-review.md # Quality pass applied to a drafted plan + plan-templates/ # minimal, standard, extensive, phases, success criteria + review-agent-instructions.md # Instructions passed to each review agent + review-consolidation.md # Deduplicate, order, and number findings + review-dispatch.md # Caller-side procedure for launching review agents + review-report-template.md # Shape of the consolidated report + validate-and-fix.md # Run linter and tests, fix, retry up to 3 times scripts/ # detect-base-branch.sh, detect-review-scope.sh ``` -Each skill directory may also carry a `references/` folder (deeper procedure docs) and a `scripts/` folder (helper shell scripts). +Each skill directory may also carry a `references/` folder (deeper procedure docs) and a `scripts/` folder (helper shell scripts). A shared reference appears in each consuming skill as a symlink, so the skill always links it by its own local path. + +## Authoring Conventions + +A `SKILL.md` carries the workflow and the opinions behind it; everything else is demoted to +`references/` or cut. Before adding or trimming a section, apply the KEEP / DEMOTE / DELETE +rubric in `CONTRIBUTING.md` → _What belongs in a `SKILL.md`_. Two rules it is easy to get +backwards: + +- The frontmatter `description` is the router and loads before the body, so it carries the + whole trigger surface. Never trim it for length, and never split it across a second field. +- An agent's `description` is paid for on every request, run or not. Keep it expressive and + free of `` blocks (`CONTRIBUTING.md` → _Agent descriptions_). ## Philosophy diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a72291..28c0890 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ argument-hint: "feature or idea to explore" | ----- | -------- | ----- | | `name` | Yes | Lowercase letters, numbers, and hyphens only | | `user-invocable` | Yes | `true` if the user can invoke this skill directly, `false` otherwise | -| `description` | Yes | Describes when the skill should be triggered | +| `description` | Yes | What the skill does **and** when to trigger it. This is the whole trigger surface — there is no separate `when_to_use` field | | `argument-hint` | No | Placeholder hint shown to the user | After the frontmatter, structure the file as: @@ -68,11 +68,66 @@ Add the new skill directory and its files to the repository structure tree in `A - **Provide complete, copy-pasteable snippets** — not fragments. - **Reference packages by full name** (e.g., `package:mocktail`, not just "mocktail"). - **Show anti-patterns alongside correct patterns** when helpful, so readers understand both what to do and what to avoid. -- **Keep prose tight** — every word in a SKILL.md consumes tokens in the model's context window. Verbose instructions reduce the space available for the user's actual work. Apply these techniques: - - **Decision tables over prose chains** — replace long if/else narratives with a table or compact bulleted list. - - **One sentence per rule** — if a guideline needs a paragraph to explain, it may be too complex or doing too much. - - **Cut redundancy** — don't restate in an "Important" footer what the body already says. - - **Collapse conditional blocks** — when multiple branches share structure, describe the shared part once and list only what differs. +- **Decision tables over prose chains** — replace long if/else narratives with a table or compact bulleted list. +- **One sentence per rule** — if a guideline needs a paragraph to explain, it may be too complex or doing too much. +- **Collapse conditional blocks** — when multiple branches share structure, describe the shared part once and list only what differs. +- **Apply the KEEP / DEMOTE / DELETE rubric below** to decide what earns a place in the `SKILL.md` at all. + +## What belongs in a `SKILL.md` + +A skill earns its tokens by carrying what the model *cannot* infer: the workflow's decision +points and the opinions this team holds about them. Generic advice the model already applies +displaces those opinions and slows routing. + +Every section you write gets one of three verdicts. + +**KEEP in `SKILL.md`** — the workflow, and the judgement calls it encodes: + +- Gates and their thresholds — the hotfix blast radius, three fix attempts before escalating, + the `success-criteria` contract `/build` consumes +- Decision tables that route the run — which template, whether to research externally, which + agent set to dispatch +- VGV opinions the model would not reach by default — tests are non-negotiable, YAGNI, one + implementation phase per context window, clear-context handoff offered first +- Harness facts — **AskUserQuestion**, `$ARGUMENTS`, `${CLAUDE_SKILL_DIR}`, the skill + directory boundary, `allowed-tools` patterns +- Safety rules — never push without approval, never stage secret files + +**DEMOTE to `references/`** — needed at one point in the run, not at load time: + +- Document templates and rendered output formats +- Any procedure two or more skills share (see [Sharing content across skills](#sharing-content-across-skills)) +- Deep-dive detail that only one branch of the workflow reaches + +**DELETE** — no new information at any load time: + +- A trailing `## Important` or `## Key Principles` block that restates the body. The body is + read in order, so a summary at the end informs nothing. When a line there is load-bearing, + move it to the step it governs — or to the opening paragraph when it governs the whole skill. +- Instructions duplicated between the `description` and the body, or between two steps +- Handoff option lists repeated verbatim for a second branch of the same question + +Two things this rubric does **not** apply to: + +- **The frontmatter `description`.** It is the router and loads before the body, so every + trigger phrase is load-bearing. Do not trim it for length, and do not assume a phrase is + redundant because the body repeats it — routing happens before the body is ever read. +- **Hard constraints.** Directive density is not the defect; generic restatement is. A rule + that changes what the model does stays, and stays hard. + +Wingspan's skills are procedural — the steps *are* the content — so there is no line target. +The test is per section: does this change what the model does at the point it is read? + +## Agent descriptions + +An agent's `description` is concatenated into the agent listing on **every** request, so its +cost is paid each turn across all ten agents, whether or not any of them runs. + +Write a description expressive enough to route on its own: what the agent inspects, what it +returns, and when to reach for it. Do not add `` blocks — a well-shaped description +routes better than worked examples and costs a fraction of the tokens. Wingspan's agents are +dispatched by name from the skills that need them, so examples bought no routing accuracy at +all; removing them cut roughly 2,400 tokens from every request. ## Shared Resources & Skill Boundaries diff --git a/agents/analysis/plan-splitting-agent.md b/agents/analysis/plan-splitting-agent.md index a866118..06dd9f3 100644 --- a/agents/analysis/plan-splitting-agent.md +++ b/agents/analysis/plan-splitting-agent.md @@ -1,34 +1,6 @@ --- name: plan-splitting-agent -description: | - Analyzes implementation plans for scope and recommends splitting large plans into multiple independently-mergeable PRs. Use during plan creation and technical review to catch oversized plans before development begins. - - - - Context: Developer runs /plan-technical-review on a large feature plan. - user: "Review this plan for the new authentication flow — it touches API client, repository, state management, and three screens." - assistant: "I'll run the plan-splitting agent to assess whether this should be split across multiple PRs." - - Plans spanning multiple layers (data, domain, presentation) with new packages are strong candidates for splitting. - - - - Context: Developer runs /plan-technical-review on a small bug fix. - user: "Review this plan for fixing the cart total calculation." - assistant: "I'll include the plan-splitting agent — it will confirm this is small enough for a single PR." - - Small, focused plans should pass through quickly with a "no split needed" assessment. - - - - Context: Developer has a large but tightly coupled plan. - user: "Review this plan — it adds a single complex component with its state management, repository, and API client, all interdependent." - assistant: "I'll run the plan-splitting agent to check if this can be split, or if the coupling means it should stay as one PR." - - Not all large plans can be split. The agent should recognize tight coupling and recommend keeping as a single PR with a scope warning rather than forcing an awkward split. - - - +description: Analyzes an implementation plan's scope and recommends whether to split it into multiple independently-mergeable PRs. Returns either proposed PR boundaries with their dependency order, or a no-split verdict — including for a plan that is large but too tightly coupled to divide, which returns a scope warning instead. Use during plan creation and technical review, before development begins. model: sonnet effort: medium --- diff --git a/agents/codebase-review/code-simplicity-review-agent.md b/agents/codebase-review/code-simplicity-review-agent.md index ac9c3b6..22ffa5e 100644 --- a/agents/codebase-review/code-simplicity-review-agent.md +++ b/agents/codebase-review/code-simplicity-review-agent.md @@ -1,35 +1,7 @@ --- name: code-simplicity-review-agent skills: [elements-of-style] -description: | - Final review pass to ensure code is as simple and minimal as possible. Use after implementation is complete to identify YAGNI violations and simplification opportunities. - - - - Context: The user finished a feature and wants it trimmed before merge. - user: "I just finished the onboarding flow — can you check it's not over-engineered?" - assistant: "I'll use the code-simplicity review agent to flag YAGNI violations and simplification opportunities." - - Completed features often carry premature abstractions and dead code; the simplicity agent identifies what to remove. - - - - Context: The user added an abstraction and isn't sure it earns its keep. - user: "I added a generic BaseRepository — is it worth it for one repository?" - assistant: "Let me run the code-simplicity review agent to check whether the abstraction is justified." - - Single-implementation abstractions are a common YAGNI violation the simplicity agent flags for removal. - - - - Context: A pre-PR pass to cut complexity. - user: "Before I open the PR, is there anything here I can simplify?" - assistant: "I'll use the code-simplicity review agent to find complexity that can be removed." - - A final simplicity pass reduces cognitive load and maintenance cost before review. - - - +description: Final review pass over completed code for YAGNI violations, premature abstraction, and dead code. Returns findings that name what to remove and why an abstraction does not earn its keep — single-implementation interfaces, options no caller passes, hypothetical extension points. Use after implementation is complete, before opening a PR. model: sonnet effort: medium --- diff --git a/agents/codebase-review/codebase-review-agent.md b/agents/codebase-review/codebase-review-agent.md index 4878b00..b349604 100644 --- a/agents/codebase-review/codebase-review-agent.md +++ b/agents/codebase-review/codebase-review-agent.md @@ -1,35 +1,7 @@ --- name: codebase-review-agent skills: [elements-of-style] -description: | - Conducts a thorough review of the given codebase, ensures code quality standards are met, and validates that the codebase uses consistently the same patterns. - - - - Context: User wants to understand the codebase structure and conventions before contributing. - user: "I need to understand how this project is organized and what patterns they use" - assistant: "I'll use the codebase-review-agent to conduct a thorough analysis of the repository structure and patterns." - - Since the user needs comprehensive codebase research, use the codebase-review-agent to examine all aspects of the project. - - - - Context: User is preparing to create a GitHub issue and wants to follow project conventions. - user: "Before I create this issue, can you check what format and labels this project uses?" - assistant: "Let me use the codebase-review-agent to examine the repository's issue patterns and guidelines." - - The user needs to understand issue formatting conventions, so use the codebase-review-agent to analyze existing issues and templates. - - - - Context: User is implementing a new feature and wants to follow existing patterns. - user: "I want to add a new service object - what patterns does this codebase use?" - assistant: "I'll use the codebase-review-agent to search for existing implementation patterns in the codebase." - - Since the user needs to understand implementation patterns, use the codebase-review-agent to search and analyze the codebase. - - - +description: Surveys a codebase's structure, conventions, and pattern consistency. Returns the established pattern for the area under review, the files that best demonstrate it, the project's own guidance (CLAUDE.md, issue and PR templates), and any place the pattern is applied inconsistently. Use to orient in unfamiliar code, or to find the representative example a new implementation should follow. model: sonnet effort: medium --- diff --git a/agents/codebase-review/vgv-review-agent.md b/agents/codebase-review/vgv-review-agent.md index 123f31b..114f514 100644 --- a/agents/codebase-review/vgv-review-agent.md +++ b/agents/codebase-review/vgv-review-agent.md @@ -1,43 +1,7 @@ --- name: vgv-review-agent skills: [elements-of-style] -description: | - Reviews code against Very Good Ventures engineering standards. Use after implementing features, modifying code, creating new packages, or before opening PRs. Enforces architecture, state management conventions, testing quality, and code simplicity. - - - - Context: The user has just implemented a new feature with state management and wants it reviewed. - user: "I just finished implementing the authentication feature with a new service and state management" - assistant: "I'll use the VGV review agent to evaluate this implementation against our engineering standards." - - New state management implementations should be reviewed for proper design, layer separation, test coverage, and adherence to VGV conventions. - - - - Context: The user has added state management that deviates from the project pattern. - user: "I added a different state management approach for managing the shopping cart state" - assistant: "Let me invoke the VGV review agent to analyze this architectural decision." - - Using a different state management pattern than the project standard is an architectural deviation that should be reviewed critically. - - - - Context: The user has created a new package in the monorepo. - user: "I've created a new package under packages/ for the payments feature" - assistant: "I'll have the VGV review agent check the package structure, layering, and conventions." - - New packages should follow the project's monorepo conventions, layer separation, linting setup, and testing scaffolding. - - - - Context: The user has refactored existing code and wants a quality check. - user: "I refactored the user profile feature to reduce code duplication" - assistant: "Let me run the VGV review agent to ensure the refactor maintains our quality bar and doesn't introduce regressions." - - Refactors to existing code should be reviewed strictly for regressions, clarity improvements, and whether the changes actually simplify rather than shift complexity. - - - +description: Reviews code against Very Good Ventures engineering standards — architecture, layer separation, state management conventions, testing quality, and code simplicity. Returns findings graded Critical, Important, or Suggestion. Use after implementing a feature, adding a package, or refactoring, and before opening a PR. Reviews deviations from the project's established state-management pattern most strictly. model: inherit --- diff --git a/agents/quality-review/architecture-review-agent.md b/agents/quality-review/architecture-review-agent.md index beecfda..67ac7f8 100644 --- a/agents/quality-review/architecture-review-agent.md +++ b/agents/quality-review/architecture-review-agent.md @@ -1,35 +1,7 @@ --- name: architecture-review-agent skills: [elements-of-style] -description: | - Validates project architecture against VGV standards post-implementation. Use after writing code to verify layer separation, state management correctness, dependency direction, and package structure. - - - - Context: The user has implemented a new feature across multiple layers and wants an architecture check. - user: "I just added the checkout feature with a new service, repository, and API client. Is the architecture clean?" - assistant: "I'll use the architecture review agent to validate layer separation and dependency direction." - - Multi-layer implementations need verification that presentation doesn't import data directly, dependencies flow correctly, and state management patterns are proper. - - - - Context: The user has added a new package to a monorepo. - user: "I created a new payments package. Can you check it follows our architecture?" - assistant: "Let me run the architecture review agent to verify the package structure and layer boundaries." - - New packages must have a proper dependency manifest, linting configuration, correct layer separation, and proper dependency direction. - - - - Context: The user has refactored state management and wants validation. - user: "I converted the settings feature to use a different state management approach. Is everything wired correctly?" - assistant: "I'll use the architecture review agent to verify the state management implementation follows VGV conventions." - - State management migrations need careful review: naming should be descriptive, states should be immutable, no business logic in UI, and proper provider/injection usage. - - - +description: Validates implemented architecture against VGV standards — layer separation, dependency direction, state management wiring, and package structure. Returns each violation with the offending import or boundary, so a presentation layer reaching into data, or a package missing its dependency manifest and lint config, comes back named. Use after writing code that spans layers, adds a package, or migrates state management. model: inherit --- diff --git a/agents/quality-review/test-quality-review-agent.md b/agents/quality-review/test-quality-review-agent.md index 264d912..adf1189 100644 --- a/agents/quality-review/test-quality-review-agent.md +++ b/agents/quality-review/test-quality-review-agent.md @@ -1,35 +1,7 @@ --- name: test-quality-review-agent skills: [elements-of-style] -description: | - Reviews test coverage and quality for implementations. Use after code is written to verify every state management unit, repository, and UI component has proper tests following VGV conventions. - - - - Context: The user has finished implementing a feature and wants test coverage reviewed. - user: "I just finished implementing the notifications feature with tests. Can you review the test quality?" - assistant: "I'll use the test quality review agent to evaluate coverage and adherence to project testing patterns." - - New feature implementations need test coverage verification: every state management unit, UI component, and repository must have a test file following VGV conventions. - - - - Context: The user has written state management tests and wants to check for anti-patterns. - user: "I wrote tests for the cart service — are they solid?" - assistant: "Let me run the test quality review agent to check for anti-patterns and coverage gaps." - - State management tests should follow VGV conventions, cover success/failure/edge cases, use proper mocking, and avoid tautological assertions. - - - - Context: The user wants a pre-PR test quality check. - user: "Before I open a PR, can you verify the tests are up to standard?" - assistant: "I'll use the test quality review agent to audit test quality across the changed files." - - Pre-PR test reviews should verify completeness, pattern compliance, meaningful assertions, and absence of anti-patterns. - - - +description: Reviews test coverage and quality — whether every state management unit, repository, data model, and UI component has a test file, and whether those tests cover success, failure, and edge cases with meaningful assertions. Returns coverage gaps and anti-patterns, including tautological assertions and missing async settling. Use after code is written, before opening a PR. model: sonnet --- diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index a750ac9..5869a0b 100644 --- a/skills/brainstorm/SKILL.md +++ b/skills/brainstorm/SKILL.md @@ -1,8 +1,7 @@ --- name: brainstorm user-invocable: true -description: Explores requirements and approaches through collaborative dialogue before planning implementation. -when_to_use: Use when user says "brainstorm", "explore idea", "what should we build", "think through this", or "let's discuss approaches". +description: Explores requirements and approaches through collaborative dialogue before planning implementation. Use when the user says "brainstorm", "explore idea", "what should we build", "think through this", or "let's discuss approaches". argument-hint: feature or idea to explore compatibility: Designed for Claude Code (or similar products with agent support) --- @@ -11,6 +10,8 @@ compatibility: Designed for Claude Code (or similar products with agent support) Clarify **WHAT** to build before diving into **HOW** to build it. Explore user intent, approaches, and design decisions through collaborative dialogue. +**Do not write code.** The output is a brainstorm document. + ## Feature description $ARGUMENTS @@ -73,6 +74,9 @@ Use the **AskUserQuestion tool** to ask questions one at a time. The tool automa | Edge Cases | What shouldn't happen? Any error states to consider? | | Existing Patterns | Are there similar features in the codebase to follow? | +Present the emerging design in sections and validate each one as you go, rather than saving it all +for the document. + **Exit condition:** Continue until the idea is clear OR user says "proceed" or "let's move on." #### 1.3. Explore approaches @@ -101,9 +105,7 @@ Use **AskUserQuestion tool** to ask which approach the user prefers. #### 1.4. Set up workspace -Before writing any files, ensure the session is not on the base branch: - -- Run `git rev-parse --abbrev-ref HEAD`. If the current branch is a base branch (`main`, `master`, or `develop`), use **AskUserQuestion** to offer creating a feature branch — `git checkout -b /`, name under 60 characters — before writing. If already on a feature branch, continue without prompting. +Run the [feature branch check](references/feature-branch.md) before writing anything to disk. ### 2. Capture the design document @@ -115,27 +117,15 @@ Use the [brainstorm template](references/template.md) as the document structure. ### 3. Handoff -Use **AskUserQuestion tool** to consider next steps: - -**Question**: "Brainstorm complete! What would you like to do next?" +Use the **AskUserQuestion tool**: "Brainstorm complete! What would you like to do next?" -**Options:** 1. **Clear context and plan (Recommended)**: clear context for a fresh start, then plan 2. **Continue with planning**: run the `/plan` skill to create a detailed implementation plan -3. **Review and refine approach:** improve the document using structured review +3. **Review and refine approach**: improve the document using structured review 4. **Done for now**: brainstorm complete. To start planning later: `/plan` -**If the user selects "Clear context and plan"** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/plan` with the actual brainstorm doc path. Then stop. - -**If the user selects "Review and refine approach"** then apply the @refine-approach skill to the document. - -When `refine-approach` is complete, present these options: - -1. **Clear context and plan (Recommended)**: clear context for a fresh start, then plan -2. **Move to planning**: run the `/plan` skill to create a detailed implementation plan -3. **Done for now**: ideation complete. To start planning later: `/plan` - -**If the user selects "Clear context and plan"** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/plan` with the actual brainstorm doc path. Then stop. +- **Clear context and plan** → follow the [clear context handoff](references/clear-context-handoff.md) for `/plan` with the actual brainstorm doc path, then stop. +- **Review and refine approach** → apply the @refine-approach skill to the document, then present these same options again without the refine one. ## Output Summary @@ -150,16 +140,3 @@ Key decisions: - [Decision 1] - [Decision 2] ``` - -## Key Principles - -- **One question at a time** - Don't overwhelm with multiple questions -- **Multiple choice preferred** - Easier to answer than open-ended when possible -- **YAGNI ruthlessly** - Remove unnecessary features from all designs -- **Explore alternatives** - Always propose 2-3 approaches before settling -- **Incremental validation** - Present design in sections, validate each -- **Be flexible** - Go back and clarify when something doesn't make sense - -## Important Guidelines - -**DO NOT CODE!** Just explore and document decisions. diff --git a/skills/brainstorm/references/feature-branch.md b/skills/brainstorm/references/feature-branch.md new file mode 120000 index 0000000..22ae6b5 --- /dev/null +++ b/skills/brainstorm/references/feature-branch.md @@ -0,0 +1 @@ +../../shared/references/feature-branch.md \ No newline at end of file diff --git a/skills/build/SKILL.md b/skills/build/SKILL.md index c0edb49..62949f8 100644 --- a/skills/build/SKILL.md +++ b/skills/build/SKILL.md @@ -1,8 +1,7 @@ --- name: build user-invocable: true -description: Executes an implementation plan — writes code and tests, runs quality review, and ships a pull request. -when_to_use: Use when user says "build this", "implement the plan", "start coding", "execute the plan", or "ship it". +description: Executes an implementation plan — writes code and tests, runs quality review, and ships a pull request. Use when the user says "build this", "implement the plan", "start coding", "execute the plan", or "ship it". effort: high argument-hint: plan file path allowed-tools: Bash(rm -rf docs/reviews/) @@ -11,7 +10,7 @@ compatibility: Designed for Claude Code (or similar products with agent support) # Execute an implementation plan -Take a plan from `docs/plan/` and turn it into shipped code: implement features, write tests, and validate quality. +Take a plan from `docs/plan/` and turn it into shipped code: implement features, write tests, and validate quality. This is the execution phase. The plan was already reviewed and approved — follow it rather than redesigning it. ## Build Progress @@ -47,12 +46,7 @@ Do not proceed without a plan. **After loading the plan:** parse title, type, the `success-criteria` block, tasks, file paths, and the `## Implementation Phases` section if present. -**Commit autonomy:** decide once how this build commits, and carry the choice through the whole run. Honor a saved preference if one exists (Claude memory or the user's personal settings); otherwise use **AskUserQuestion**: - -- **Auto-commit each phase (Recommended)**: commit automatically as each phase completes. Pushing and opening the PR still pause for approval (Phase 4). -- **I'll commit myself**: build one phase, then stop so the user reviews and commits. Nothing is committed or pushed without the user. - -Offer to save the choice to Claude memory (a personal preference) so future builds skip this question. Save it as the user's own preference — never write it to the project's CLAUDE.md, since committing this is a per-developer choice, not a repo convention. +**Commit autonomy:** settle it now, before any code is written, per [commit autonomy](references/commit-autonomy.md). The choice holds for the whole run. **Resuming a phased build:** if the plan has an `## Implementation Phases` section with at least one phase already marked `**Status:** Done`, this is a resumed build. Announce "Resuming at Phase N: [name]" — the first phase whose status is not `Done` — and go straight to Phase 1 for that phase. Skip the scope-confirmation question below. @@ -108,20 +102,7 @@ Run the phase's **Validation** steps, then follow the [validation and fix proced Set this phase's `**Status:**` to `Done` in the plan file — this marker lets a build resume the right phase after a context clear (the plan is a local artifact, so it survives `/clear`). -Then handle the phase's changes per the **commit autonomy** chosen in Phase 0: - -- **Auto-commit each phase** → stage and commit the phase now, using the format below. -- **I'll commit myself** → do not commit. Summarize the phase's changed files and leave them staged for the user to review. - -Auto-commit message format: - -```text -: - - -``` - -`` matches the plan's type (`feat`, `fix`, `refactor`, …). One commit per phase keeps the branch history clean and each phase independently reviewable. A single-phase plan produces one implementation commit here. +Then handle the phase's changes per the [commit autonomy](references/commit-autonomy.md) chosen in Phase 0. #### Step 5: Checkpoint @@ -151,15 +132,9 @@ Once the final phase is committed, follow the [surgical-diff gate](references/su ## Phase 3 — Quality Review -Once the final phase is committed and the surgical-diff gate has run, review the whole branch. Run 5 review agents **in parallel** — they review the full branch diff, so this runs once after the last phase, not per phase. - -### Agent instructions +Once the final phase is committed and the surgical-diff gate has run, review the whole branch. The agents review the full branch diff, so this runs once after the last phase, not per phase. -Run `pwd` and let `` be the result — subagents may change directories, making relative paths unreliable. - -Each agent prompt must include the [review agent instructions](references/review-agent-instructions.md) with `` set to `/docs/reviews/raw` and `` set to the agent's report name below (a bare stem — the agent writes `/.md`). Substitute `` with the absolute path. - -The 5 agents and their report names (``): +Dispatch them per [review agent dispatch](references/review-dispatch.md), with `` = `/docs/reviews/raw` and these 5 agents: | Agent | Report name | | ----- | ----------- | @@ -169,8 +144,6 @@ The 5 agents and their report names (``): | **@code-simplicity-review-agent** | `code-simplicity-review` | | **@pr-readiness-review-agent** | `pr-readiness-review` | -If an agent fails, note it, continue with the rest, and record the failure in the report header. - ### After all reviews complete Follow the [review consolidation procedure](references/review-consolidation.md): deduplicate the agents' structured findings, order them deterministically, assign stable `FINDING-NN` ids, and write **one** consolidated file to `/docs/reviews/review.md` using the [report template](references/review-report-template.md). Print the aligned chat summary (same ids, order, and titles as the file). Then act: auto-fix minor issues, fix Critical findings by id, present Important findings to the user, and note any still-deferred findings in the PR description. @@ -179,16 +152,7 @@ Follow the [review consolidation procedure](references/review-consolidation.md): ### Drive to green -The plan's `success-criteria` block is the ship gate. Parse it, then handle these cases before looping: - -| Case | Action | -| ---- | ------ | -| Block present with a `VERIFICATION COMMAND` | Gate set = the non-manual `verify:` commands; authoritative command = the `VERIFICATION COMMAND`. | -| Block present, `VERIFICATION COMMAND` missing but non-manual `verify:` lines exist | Synthesize the authoritative command by joining those `verify:` commands with `&&`. | -| Only `verify: manual` criteria, no runnable command | Skip the loop; go straight to the manual-criteria checklist. Never treat an empty runnable set as green. | -| No `success-criteria` block (plan predates it) | Fall back to the detected project suite (formatter, linter, test runner) as the gate, and warn the user the plan has no machine-checkable criteria. Never treat an absent block as green. | - -Then follow the [drive to green procedure](references/drive-to-green.md) with that gate set and authoritative command. It loops until every gate is green by real output, delegates to a matching installed verification skill when one exists, runs the authoritative command as the final check, and escalates only on un-runnable or self-contradictory criteria. Do not proceed to cleanup until the authoritative gate is green and any manual criteria are confirmed. +Resolve the gate set and run the loop per [ship gate](references/ship-gate.md). ### Cleanup @@ -198,32 +162,9 @@ Remove the review reports — their findings have already been addressed or reco rm -rf docs/reviews/ ``` -### Commit - -Handle the outstanding changes — the drive-to-green loop, the surgical-diff gate, and the Phase 3 review fixes — per the **commit autonomy** chosen in Phase 0: - -- **Auto-commit mode** → the phases are already committed from Phase 2; stage and commit whatever is still outstanding, using the format below. If nothing is outstanding, skip this commit. -- **I'll-commit-myself mode** → do not commit. Summarize everything still uncommitted and leave it staged for the user. - -```text -: address review findings - - -``` - -`` matches the plan's type (`feat`, `fix`, `refactor`, etc.). Either way, review findings -are fixed in place during Phase 3 and the report is deleted at Cleanup, so any commit does not -cite `FINDING-NN` ids (there would be no report left to map them to). - -### Ship +### Commit and push -Whatever commits this build produced are local. Pushing and opening a PR is outward-facing, so gate it on the user's preference — separately from the commit-autonomy choice: - -- **User has a saved preference to push automatically** (Claude memory or personal settings) → push and open the PR without asking. -- **No such preference** → use **AskUserQuestion** before anything leaves the machine: - 1. **Review locally first (Recommended)**: stop here. The commits stay local; the user pushes and opens the PR when ready. Do not call `/create-pr`. - 2. **Push and open the PR now**: proceed this once. - 3. **Always push automatically**: proceed, and save the preference to Claude memory (the user's own preference, never the project's CLAUDE.md) so future builds skip this prompt. +Handle the outstanding changes — the drive-to-green loop, the surgical-diff gate, and the Phase 3 review fixes — per [commit autonomy](references/commit-autonomy.md), which also gates pushing. To push, call `/create-pr skip-checks` — it pushes and opens the PR. Validation already ran above. The PR body uses the [PR template](references/pr-template.md). @@ -240,10 +181,3 @@ Use **AskUserQuestion** to present options: - Generated files (mocks, codegen output) must be regenerated after code changes — stale generated files cause confusing test failures. - If the plan specifies file paths that conflict with existing files, confirm with the user before overwriting. The codebase may have changed since the plan was written. - The consolidated report (`docs/reviews/review.md`) and per-agent raw reports (`docs/reviews/raw/`) are deleted after Phase 4. If the build is interrupted, stale reports may remain — delete `docs/reviews/` manually before the next run. - -## Important - -- This skill writes code. It is the execution phase, not the planning phase. -- Follow the plan. The plan was reviewed and approved. Don't redesign during implementation. -- Ship quality, not quantity. Every line represents VGV's engineering reputation. -- When in doubt, read the plan again before asking the user. diff --git a/skills/build/references/commit-autonomy.md b/skills/build/references/commit-autonomy.md new file mode 100644 index 0000000..68a2ea9 --- /dev/null +++ b/skills/build/references/commit-autonomy.md @@ -0,0 +1,50 @@ +# Commit Autonomy + +Decide once, in Phase 0, how this build commits; carry the choice through the whole run. +Honor a saved preference if one exists. Otherwise use **AskUserQuestion**: + +- **Auto-commit each phase (Recommended)** — commit as each phase completes. Pushing and + opening the PR still pause for approval. +- **I'll commit myself** — build one phase, then stop so the user reviews and commits. + Nothing is committed or pushed without them. + +The choice is a per-developer preference, not a repo convention, so it never belongs in the +project's `CLAUDE.md`. + +## Applying it + +| Moment | Auto-commit | I'll commit myself | +| ------ | ----------- | ------------------ | +| A phase completes (Phase 2, Step 4) | Stage and commit the phase | Summarize the changed files, leave them staged, stop | +| Review fixes and drive-to-green land (Phase 4) | Commit whatever is still outstanding; skip if nothing is | Summarize everything uncommitted, leave it staged | + +Commit message formats: + +```text +: + + +``` + +```text +: address review findings + + +``` + +`` matches the plan's type (`feat`, `fix`, `refactor`, …). One commit per phase keeps +the branch history clean and each phase independently reviewable; a single-phase plan +produces one implementation commit. Review findings are fixed in place and the report is +deleted at cleanup, so no commit cites `FINDING-NN` ids — there would be no report left to +map them to. + +## Pushing + +Pushing is outward-facing, so it is gated separately from the commit choice. With a saved +preference to push automatically, push and open the PR without asking. Otherwise use +**AskUserQuestion** before anything leaves the machine: + +1. **Review locally first (Recommended)** — stop here; the commits stay local and the user + opens the PR when ready. Do not call `/create-pr`. +2. **Push and open the PR now** — proceed this once. +3. **Always push automatically** — proceed, and remember the preference for future builds. diff --git a/skills/build/references/review-dispatch.md b/skills/build/references/review-dispatch.md new file mode 120000 index 0000000..0ee87b7 --- /dev/null +++ b/skills/build/references/review-dispatch.md @@ -0,0 +1 @@ +../../shared/references/review-dispatch.md \ No newline at end of file diff --git a/skills/build/references/ship-gate.md b/skills/build/references/ship-gate.md new file mode 100644 index 0000000..99916b7 --- /dev/null +++ b/skills/build/references/ship-gate.md @@ -0,0 +1,17 @@ +# Ship Gate + +The plan's `success-criteria` block is the ship gate. Parse it and resolve the gate set and +the authoritative command before running the drive-to-green loop. + +| Case | Gate set and authoritative command | +| ---- | ---------------------------------- | +| Block present with a `VERIFICATION COMMAND` | Gate set is the non-manual `verify:` commands; the `VERIFICATION COMMAND` is authoritative | +| Block present, `VERIFICATION COMMAND` missing, non-manual `verify:` lines exist | Synthesize the authoritative command by joining those `verify:` commands with `&&` | +| Only `verify: manual` criteria | Skip the loop; go straight to the manual-criteria checklist | +| No `success-criteria` block (plan predates it) | Fall back to the detected project suite — formatter, linter, test runner — and warn the user the plan has no machine-checkable criteria | + +Never treat an empty runnable set or an absent block as green. + +Then follow the [drive to green procedure](drive-to-green.md) with that gate set and +authoritative command. Do not proceed to cleanup until the authoritative gate is green and +any manual criteria are confirmed. diff --git a/skills/create-pr/SKILL.md b/skills/create-pr/SKILL.md index cadee17..9c781fd 100644 --- a/skills/create-pr/SKILL.md +++ b/skills/create-pr/SKILL.md @@ -1,7 +1,6 @@ --- name: create-pr -description: Stage, commit, push, and open a pull request following project conventions and the Conventional Commits spec. Accepts optional skip-checks argument to bypass validation when called from /build. -when_to_use: Use when user says "create a PR", "open a PR", "ship it", "submit a pull request", or "open a merge request", or when work on a branch is complete and ready to publish for review. +description: Stage, commit, push, and open a pull request following project conventions and the Conventional Commits spec. Accepts an optional skip-checks argument to bypass validation when called from /build. Use when the user says "create a PR", "open a PR", "submit a pull request", or "open a merge request", or when work on a branch is complete and ready to publish for review. argument-hint: "[optional: skip-checks | ticket/issue number e.g. VGV-123 | short description]" disable-model-invocation: true allowed-tools: Bash(git push *) Bash(git add *) Bash(git commit *) Bash(gh *) Bash(glab *) diff --git a/skills/create/SKILL.md b/skills/create/SKILL.md index 9cb2ff6..83f6303 100644 --- a/skills/create/SKILL.md +++ b/skills/create/SKILL.md @@ -1,8 +1,7 @@ --- name: create user-invocable: true -description: Scaffolds a new project by routing to the right companion plugin's create skill. -when_to_use: Use when user says "create a project", "new flutter app", "start a dart package", "scaffold", or asks to set up a new codebase. +description: Scaffolds a new project by routing to the right companion plugin's create skill. Use when the user says "create a project", "new flutter app", "start a dart package", "scaffold", or asks to set up a new codebase. argument-hint: what to create (e.g., "flutter app", "dart package") effort: low allowed-tools: Read Glob Skill @@ -11,7 +10,7 @@ compatibility: Designed for Claude Code (or similar products with agent support) # Create a new project -Route project creation to the right companion plugin. Wingspan does not scaffold projects itself — it discovers companion plugins from recommendation files and delegates to the matching plugin's create skill. +Route project creation to the right companion plugin. Wingspan does not scaffold projects itself — it discovers companion plugins from recommendation files and delegates to the matching plugin's create skill. This skill is a thin router and holds no technology-specific logic. ## Project description @@ -76,8 +75,3 @@ Invoke it using the **Skill tool** with its fully qualified name (e.g., `my-plug - **No project-creation skill found for the plugin:** Inform the user the companion plugin is registered but does not provide a project-creation skill. Stop. - **If the skill invocation fails:** Surface the error to the user and suggest verifying the companion plugin is properly installed. - -## Important - -- This skill is a thin router. No technology-specific logic. -- Every user-facing question must use the **AskUserQuestion tool**. diff --git a/skills/debrief/SKILL.md b/skills/debrief/SKILL.md index e58a9d4..c247e23 100644 --- a/skills/debrief/SKILL.md +++ b/skills/debrief/SKILL.md @@ -1,8 +1,7 @@ --- name: debrief user-invocable: true -description: Produces a structured post-incident analysis — timeline, root cause, and actionable follow-ups — while context is fresh. -when_to_use: Use when user says "debrief", "post-mortem", "incident review", or "root cause analysis". +description: Produces a structured post-incident analysis — timeline, root cause, and actionable follow-ups — while context is fresh. Use when the user says "debrief", "post-mortem", "incident review", or "root cause analysis". argument-hint: incident description, PR/commit refs, or error context effort: high compatibility: Designed for Claude Code (or similar products with agent support) @@ -12,6 +11,8 @@ compatibility: Designed for Claude Code (or similar products with agent support) Produce a structured, blameless debrief document after an incident, failed release, or significant bug. Capture what happened, why, and what to change — while the context is still fresh. +**Do not make code changes.** This skill produces a document; its action items become separate tickets. + **Use this when** a production incident, failed release, flaky deploy, or significant bug warrants more than just a fix — when the team needs to understand *why* it happened and prevent recurrence. ## Incident Context @@ -74,9 +75,7 @@ Action items are recorded in the document only — they become separate tickets. ### 5. Set up workspace -Before writing the debrief file, ensure the session is not on the base branch: - -- Run `git rev-parse --abbrev-ref HEAD`. If the current branch is a base branch (`main`, `master`, or `develop`), use **AskUserQuestion** to offer creating a feature branch — `git checkout -b /`, name under 60 characters — before writing. If already on a feature branch, continue without prompting. +Run the [feature branch check](references/feature-branch.md) before writing anything to disk. ### 6. Write the debrief document @@ -102,32 +101,7 @@ Use the **AskUserQuestion tool** to present next steps: **If the user selects "Review and refine"** → apply the @refine-approach skill to the document. When refinement is complete, present these options again (without the refine option). -**If the user selects "Generate issue previews"** → read the action items from the written debrief document, then: - -1. **Check for issue templates**: look for `.github/ISSUE_TEMPLATE/` in the project root. Read every `.yaml` or `.yml` file found there (skip `config.yml`). - -2. **If templates exist**: render one preview block per action item using the most appropriate template. Map each item to a template based on its content (e.g., a missing test or validation gap → bug report; a new monitoring check → feature request; a dependency update or runbook → chore). Populate every required field defined in the template. Include a `Template:` line naming the chosen template file. - -3. **If no templates exist**: fall back to the generic format: - -```text ---- -Title: -Label: prevent | detect | respond -Body: - ## Context - Debrief: docs/debriefs/YYYY-MM-DD--debrief.md - Root cause: - - ## What happened - - - ## What to do - ---- -``` - -Render all previews in a single fenced block so the user can copy them. Do not call `gh`, `glab`, or any external CLI — output is display only. +**If the user selects "Generate issue previews"** → render the action items per [issue previews](references/issue-previews.md). ## Output Summary @@ -142,15 +116,3 @@ Severity: Root cause: [one-line summary] Action items: prevent, detect, respond ``` - -## Key Principles - -- **Blameless** — Focus on systems and processes, never individuals -- **Evidence-based** — Link findings to commits, PRs, code paths, and logs -- **Actionable** — Every action item is specific and assignable -- **Honest about gaps** — Mark unknowns explicitly rather than guessing -- **Tech-agnostic** — No language or framework assumptions in the skill itself - -## Important - -**DO NOT make code changes.** This skill produces a document only. Action items become separate tickets. diff --git a/skills/debrief/references/feature-branch.md b/skills/debrief/references/feature-branch.md new file mode 120000 index 0000000..22ae6b5 --- /dev/null +++ b/skills/debrief/references/feature-branch.md @@ -0,0 +1 @@ +../../shared/references/feature-branch.md \ No newline at end of file diff --git a/skills/debrief/references/issue-previews.md b/skills/debrief/references/issue-previews.md new file mode 100644 index 0000000..91effb7 --- /dev/null +++ b/skills/debrief/references/issue-previews.md @@ -0,0 +1,40 @@ +# Issue Previews + +Format the debrief's action items as ready-to-copy issue drafts. Read the action items back +from the written debrief document, not from memory. + +Output is display only. Do not call `gh`, `glab`, or any other external CLI — the user files +the issues themselves. + +## With project templates + +Look for `.github/ISSUE_TEMPLATE/` in the project root and read every `.yaml` or `.yml` file +there, skipping `config.yml`. + +Render one preview block per action item using the template that best fits its content — a +missing test or validation gap maps to a bug report, a new monitoring check to a feature +request, a dependency update or runbook to a chore. Populate every field the template marks +required, and include a `Template:` line naming the file you chose. + +## Without templates + +Fall back to the generic format: + +```text +--- +Title: +Label: prevent | detect | respond +Body: + ## Context + Debrief: docs/debriefs/YYYY-MM-DD--debrief.md + Root cause: + + ## What happened + + + ## What to do + +--- +``` + +Render all previews in a single fenced block so the user can copy them in one go. diff --git a/skills/elements-of-style/SKILL.md b/skills/elements-of-style/SKILL.md index f00e76e..ecf4df8 100644 --- a/skills/elements-of-style/SKILL.md +++ b/skills/elements-of-style/SKILL.md @@ -1,8 +1,7 @@ --- name: elements-of-style user-invocable: false -description: Applies Strunk's Elements of Style principles when writing or editing prose. -when_to_use: Triggers on "write clearly," "edit for style," "improve writing," or tasks requiring clear, vigorous English — documents, emails, reviews. +description: Applies Strunk's Elements of Style principles when writing or editing prose. Triggers on "write clearly", "edit for style", "improve writing", or tasks requiring clear, vigorous English — documents, emails, reviews. compatibility: Designed for Claude Code (or similar products) --- diff --git a/skills/hotfix/SKILL.md b/skills/hotfix/SKILL.md index c65a5e0..688112b 100644 --- a/skills/hotfix/SKILL.md +++ b/skills/hotfix/SKILL.md @@ -94,23 +94,15 @@ Follow the [validation and fix procedure](references/validate-and-fix.md). ## Phase 4 — Review -Run review agents **in parallel** to validate the fix. Use a reduced set — speed matters, but quality is non-negotiable. +Validate the fix with a reduced agent set — speed matters, but quality is non-negotiable. -### Agent instructions - -Run `pwd` and let `` be the result — subagents may change directories, making relative paths unreliable. - -Each agent prompt must include the [review agent instructions](references/review-agent-instructions.md) with `` set to `/docs/hotfix-review/raw` and `` set to the agent's report name below (a bare stem — the agent writes `/.md`). Substitute `` with the absolute path. - -The reduced agent set and their report names (``): +Dispatch them per [review agent dispatch](references/review-dispatch.md), with `` = `/docs/hotfix-review/raw` and these 2 agents: | Agent | Report name | |-------|-------------| | **@vgv-review-agent** | `vgv-review` | | **@test-quality-review-agent** | `test-quality-review` | -If an agent fails, note it, continue with the other, and record the failure in the report header so the reduced review isn't silently halved. - ### After reviews complete Follow the [review consolidation procedure](references/review-consolidation.md): deduplicate the agents' structured findings, order them deterministically, assign stable `FINDING-NN` ids, and write **one** consolidated file to `/docs/hotfix-review/review.md` using the [report template](references/review-report-template.md). Print the aligned chat summary (same ids, order, and titles as the file). Then fix Critical findings by id and present Important findings to the user. The report is deleted at Cleanup, so the fix commit does not cite `FINDING-NN` ids. @@ -156,11 +148,3 @@ Use **AskUserQuestion** to present options: - Hotfix branches use the `hotfix/` prefix, not `fix/`. Other skills use `fix/` — do not mix them. - If `docs/hotfix-review/` already exists from a previous interrupted hotfix, delete it before running Phase 4 to avoid stale reports contaminating the review. - The blast radius check (Phase 3) uses a threshold of 5 files. A fix that touches exactly 5 files is within threshold; 6 triggers the warning. - -## Important - -- This skill is for emergency fixes. It trades planning depth for speed, but never trades away quality. -- No brainstorm or plan documents are generated. -- Tests and review are non-negotiable — fast doesn't mean sloppy. -- Keep the diff minimal. A hotfix that grows into a feature rewrite belongs in `/plan` → `/build`. -- The commit must be cherry-pick-friendly: one commit, one concern, no unrelated changes. diff --git a/skills/hotfix/references/review-dispatch.md b/skills/hotfix/references/review-dispatch.md new file mode 120000 index 0000000..0ee87b7 --- /dev/null +++ b/skills/hotfix/references/review-dispatch.md @@ -0,0 +1 @@ +../../shared/references/review-dispatch.md \ No newline at end of file diff --git a/skills/plan-technical-review/SKILL.md b/skills/plan-technical-review/SKILL.md index a37ec2f..5b07e5c 100644 --- a/skills/plan-technical-review/SKILL.md +++ b/skills/plan-technical-review/SKILL.md @@ -1,8 +1,7 @@ --- name: plan-technical-review user-invocable: true -description: Reviews an externally-authored implementation plan for quality, VGV conventions, and scope. Plans created by /plan are already reviewed during creation. -when_to_use: Use to review a plan you did not create with /plan — a hand-written plan or one from another tool. Triggers on "review the plan", "is this plan ready", "validate my plan", or "check the plan". +description: Reviews an externally-authored implementation plan for quality, VGV conventions, and scope — a hand-written plan, or one from another tool or a teammate. Plans created by /plan are already reviewed during creation. Triggers on "review the plan", "is this plan ready", "validate my plan", or "check the plan". argument-hint: path to plan file effort: high compatibility: Designed for Claude Code (or similar products with agent support) diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md index a95d79d..d4aad27 100644 --- a/skills/plan/SKILL.md +++ b/skills/plan/SKILL.md @@ -1,8 +1,7 @@ --- name: plan user-invocable: true -description: Turns high-level brainstorming and ideas into well-structured, actionable implementation plans. -when_to_use: Use when user says "plan this", "create a plan", "how should we implement", or "write an implementation plan". +description: Turns high-level brainstorming and ideas into well-structured, actionable implementation plans. Use when the user says "plan this", "create a plan", "how should we implement", or "write an implementation plan". effort: high argument-hint: feature, bug fix, or improvement to plan compatibility: Designed for Claude Code (or similar products with agent support) @@ -10,7 +9,9 @@ compatibility: Designed for Claude Code (or similar products with agent support) # Create a new implementation plan (or bug fix) -Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown files that follow VGV conventions and best practices. This command provides flexible detail levels to match your needs. +Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown files that follow VGV conventions and best practices, at a detail level matched to the work. + +**Never write code at this stage.** The output is a plan. ## Feature Description @@ -52,7 +53,7 @@ Instead, extract what's needed from the brainstorm and run targeted searches: - Example: If planning a new state management unit, search for existing implementations in the same feature area. 3. **Read referenced files**: Read any specific files called out in the brainstorm as relevant context. -##### 1.1.1 Research decision +#### 1.1.1 Research decision Based on the findings from `0. Idea Refinement` and `1.1 Local research`, decide whether external research is needed: @@ -64,7 +65,7 @@ Based on the findings from `0. Idea Refinement` and `1.1 Local research`, decide Announce the decision briefly and proceed. User can redirect if needed. -###### 1.1.1.1 Conditional external research +#### 1.1.2 Conditional external research Only run this step if `1.1.1 Research decision` determines that external research is needed. @@ -73,7 +74,7 @@ Run these agents in parallel to gather external information: - **@official-docs-research-agent**: Fetches and synthesizes official documentation for relevant frameworks, libraries, and APIs. - **@best-practices-research-agent**: Researches and synthesizes best practices for the project's technology stack, following VGV conventions first, then official documentation, and finally industry standards. -##### 1.1.2. Consolidate research findings +#### 1.1.3 Consolidate research findings After all research steps complete, consolidate findings: @@ -85,29 +86,10 @@ After all research steps complete, consolidate findings: **Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning. -### 2. Issue planning and structure - -Think like a product manager — what would make this issue clear and actionable? - -**Title & Categorization:** - -- [ ] Draft clear, searchable issue title using the conventional commits format (e.g., `feat: add user authentication`, `fix: cart total calculation`) -- [ ] Determine issue type: enhancement, bug, refactor -- [ ] Convert title to filename: add today's date prefix, strip prefix colon, kebab-case, add `-plan` suffix - - Example: `feat: add user authentication` → `2026-01-21-feat-add-user-authentication-plan.md` - - Keep it descriptive (3-5 words after prefix) so plans are findable by context +### 2. Title, filename, and structure -**Stakeholder Analysis:** - -- [ ] Identify who will be affected by this issue (end users, developers, operations) -- [ ] Consider implementation complexity and required expertise - -**Content Planning:** - -- [ ] Choose appropriate detail level based on issue complexity and audience -- [ ] List all necessary sections for the chosen template -- [ ] Gather supporting materials (error logs, screenshots, design mockups) -- [ ] Prepare code examples or reproduction steps if applicable, name the mock filenames in the lists +Draft the plan's title, derive its filename, and gather supporting material per +[plan authoring](references/plan-authoring.md). ### 3. User Flow Analysis @@ -149,41 +131,17 @@ These criteria populate the `success-criteria` block defined in [success-criteri ### 5.1. Set up workspace -Before writing the plan file, ensure the session is not on the base branch: - -- Run `git rev-parse --abbrev-ref HEAD`. If the current branch is a base branch (`main`, `master`, or `develop`), use **AskUserQuestion** to offer creating a feature branch — `git checkout -b /`, name under 60 characters — before writing. If already on a feature branch, continue without prompting. +Run the [feature branch check](references/feature-branch.md) before writing anything to disk. -### 6. Issue creation and formatting +### 6. Write and review the plan file -**Formatting checklist:** - -- [ ] Clear heading hierarchy (##, ###) and fenced code blocks with language identifiers -- [ ] Task lists (`- [ ]`) for trackable items; collapsible `
` for lengthy content -- [ ] Link related issues/PRs (`#number`), commits (SHA), and code (GitHub permalinks) -- [ ] Include prompts or instructions that worked well during research -- [ ] Emphasize comprehensive testing given rapid AI-assisted implementation - -### 7. Final review - -**Pre-submission Checklist:** - -- [ ] Title is searchable and descriptive -- [ ] Labels accurately categorize the issue -- [ ] All template sections are complete -- [ ] Links and references are working -- [ ] Success criteria each carry a `verify:` command (or `verify: manual `) -- [ ] Add names of files in pseudo code examples and todo lists -- [ ] Add an ERD mermaid diagram if applicable for new model changes +Write the file, then check it against the formatting and pre-submission rules in +[plan authoring](references/plan-authoring.md). ## Output Format -**Filename:** Use the date and kebab-case filename from Step 2 Title & Categorization: `docs/plan/YYYY-MM-DD---plan.md` - -Examples: - -- ✅ `docs/plan/2026-01-15-feat-user-authentication-flow-plan.md` -- ❌ `docs/plan/2026-01-15-feat-thing-plan.md` (not descriptive) -- ❌ `docs/plan/feat-user-auth-plan.md` (missing date prefix) +**Filename:** `docs/plan/YYYY-MM-DD---plan.md`, derived in Step 2 — +e.g. `docs/plan/2026-01-15-feat-user-authentication-flow-plan.md`. ## Plan Review @@ -213,7 +171,3 @@ After the review completes, use the **AskUserQuestion tool** and present the fol - **Open plan in editor** → Run `open docs/plan/.md` to open the file in the user's default editor - **Review and refine** → Load `/refine-approach` skill. - **Other** (automatically provided) → Accept free text for rework or specific changes - -## Important - -NEVER CODE at this stage. Only focus on producing a plan. diff --git a/skills/plan/references/feature-branch.md b/skills/plan/references/feature-branch.md new file mode 120000 index 0000000..22ae6b5 --- /dev/null +++ b/skills/plan/references/feature-branch.md @@ -0,0 +1 @@ +../../shared/references/feature-branch.md \ No newline at end of file diff --git a/skills/plan/references/plan-authoring.md b/skills/plan/references/plan-authoring.md new file mode 100644 index 0000000..0c837cc --- /dev/null +++ b/skills/plan/references/plan-authoring.md @@ -0,0 +1,38 @@ +# Plan Authoring + +Think like a product manager — what would make this plan clear and actionable to whoever +picks it up cold? + +## Title and filename + +Draft a searchable title in Conventional Commits form (`feat: add user authentication`, +`fix: cart total calculation`) and determine the type: enhancement, bug, or refactor. + +Convert the title to the filename: prefix today's date, strip the colon after the type, +kebab-case the rest, and append `-plan`. + +`feat: add user authentication` → `docs/plan/2026-01-21-feat-add-user-authentication-plan.md` + +Keep it descriptive — three to five words after the prefix, so plans stay findable by +context. `2026-01-15-feat-thing-plan.md` is not findable; neither is a name with no date. + +## Before choosing a template + +- Identify who the change affects — end users, developers, operations — and what expertise + it demands. That sizing drives the detail level. +- Gather supporting material: error logs, screenshots, design mockups, reproduction steps. +- Name the mock filenames in task lists, so the plan's file paths match what `/build` writes. + +## Formatting the plan file + +- Heading hierarchy (`##`, `###`) and fenced code blocks with language identifiers. +- Task lists (`- [ ]`) for trackable items; collapsible `
` for lengthy content. +- Link related issues and PRs (`#number`), commits (SHA), and code (repository permalinks). +- Carry forward any research prompt or instruction that worked well, so a rerun can reuse it. +- Add an ERD mermaid diagram when the plan introduces or changes data models. + +## Before presenting the plan + +Confirm every template section is filled, every link resolves, and every success criterion +carries a `verify:` command or `verify: manual `. A criterion with no `verify:` is the +one thing `/build` cannot act on. diff --git a/skills/rebase/SKILL.md b/skills/rebase/SKILL.md index 863e131..d569360 100644 --- a/skills/rebase/SKILL.md +++ b/skills/rebase/SKILL.md @@ -2,8 +2,7 @@ name: rebase user-invocable: true disable-model-invocation: true -description: Rebases the current feature branch onto the base branch (main/master/develop). -when_to_use: Use when user says "rebase", "sync branch", or "update branch". +description: Rebases the current feature branch onto the base branch (main/master/develop). Use when the user says "rebase", "sync branch", or "update branch". allowed-tools: Bash(*/scripts/detect-base-branch.sh) Bash(git fetch *) Bash(git rebase *) Bash(git stash *) effort: low compatibility: Designed for Claude Code (or similar products with git access) @@ -11,7 +10,7 @@ compatibility: Designed for Claude Code (or similar products with git access) # Rebase onto base branch -Rebase the current feature branch onto the latest base branch to keep it up-to-date and prevent merge conflicts from accumulating. +Rebase the current feature branch onto the latest base branch to keep it up-to-date and prevent merge conflicts from accumulating. This skill manages git state only — it never modifies project files. ## Step 1: Validate preconditions @@ -97,8 +96,3 @@ Inform the user that the rebase had conflicts and suggest resolving manually: - `git stash pop` can itself cause conflicts if stashed changes overlap with rebased commits. If stash pop fails, inform the user and suggest `git stash show` to review the stashed changes. - Detached HEAD state (`HEAD` instead of a branch name) means the user is not on any branch. Inform them and stop — do not attempt to rebase. - If the base branch does not exist locally but does on the remote, `git fetch` in Step 2 will create the remote tracking ref. The rebase uses `origin/`, not the local branch. - -## Important - -- This skill only manages git state. Do not modify project files. -- If changes were stashed, always restore them — even if the rebase fails. diff --git a/skills/refine-approach/SKILL.md b/skills/refine-approach/SKILL.md index 11cb213..763f9e7 100644 --- a/skills/refine-approach/SKILL.md +++ b/skills/refine-approach/SKILL.md @@ -1,8 +1,7 @@ --- name: refine-approach user-invocable: true -description: Reviews and refines brainstorm or planning documents before implementation. Identifies gaps, clarifies assumptions, and ensures the approach is sound. -when_to_use: Use when user says "refine this", "review my approach", or "is this ready". +description: Reviews and refines brainstorm or planning documents before implementation. Identifies gaps, clarifies assumptions, and ensures the approach is sound. Use when the user says "refine this", "review my approach", or "is this ready". argument-hint: path to document to refine compatibility: Designed for Claude Code (or similar products with agent support) --- @@ -56,7 +55,10 @@ Present your findings, then: 1. **Auto-fix** minor issues (vague language, formatting) without asking 2. **Ask approval** before substantive changes (restructuring, removing sections, changing meaning) -3. **Update** the document inline—no separate files, no metadata sections +3. **Update** the document inline — no separate files, no metadata sections + +Refine what is there. Do not rewrite the whole document, and do not add sections or +requirements the user never discussed. ### Simplification Guidance @@ -103,10 +105,3 @@ After changes are complete, ask: ### Iteration guidance After 2 refinement passes, recommend completion—diminishing returns are likely. But if the user wants to continue, allow it. - -## What NOT to Do - -- Do not rewrite the entire document -- Do not add new sections or requirements the user didn't discuss -- Do not over-engineer or add complexity -- Do not create separate review files or add metadata sections diff --git a/skills/review/SKILL.md b/skills/review/SKILL.md index 0e4f57f..e92ac89 100644 --- a/skills/review/SKILL.md +++ b/skills/review/SKILL.md @@ -1,8 +1,7 @@ --- name: review user-invocable: true -description: Runs quality review agents on demand — reviews code against VGV standards for architecture, tests, and simplicity, then writes one consolidated, numbered report. -when_to_use: Use when user says "review this code", "review my code", "code review", "review", "check this code", or "review before merging". +description: Runs quality review agents on demand — reviews code against VGV standards for architecture, tests, and simplicity, then writes one consolidated, numbered report. Use when the user says "review this code", "code review", "check this code", or "review before merging". argument-hint: "[path/to/files/or/directories (optional)]" allowed-tools: Bash(*/scripts/detect-review-scope.sh) Bash(gh *) Bash(glab *) effort: high @@ -49,23 +48,13 @@ ${CLAUDE_SKILL_DIR}/scripts/detect-review-scope.sh ## Step 2 — Run Reviews -Run `pwd` and let `` be the result — subagents may change directories, making relative -paths unreliable. Each run gets its own directory `/docs/code-review//`, so raw -per-agent reports go in `/docs/code-review//raw/` (absolute) and one run never -clobbers another branch's kept report. +Each run gets its own directory `/docs/code-review//`, so one run never clobbers +another branch's kept report. -Run the **default review agents** below **in parallel**. Projects may add agents in their -`CLAUDE.md` (include them alongside the defaults) or replace the default set entirely. - -Each agent prompt must include: - -1. **The scope constraint** — changed-file list, specific paths, or no constraint. -2. **The [review agent instructions](references/review-agent-instructions.md)** with - `` set to `/docs/code-review//raw` and `` set to the agent's - report name below (a bare stem — the agent writes `/.md`). Substitute - `` and `` with their resolved values — do not pass a relative path. - -Default agents and their report names (``): +Dispatch the **default agents** below per [review agent dispatch](references/review-dispatch.md), +with `` = `/docs/code-review//raw`. Projects may add agents in their +`CLAUDE.md` (include them alongside the defaults) or replace the default set entirely. Offer +to retry any agent that fails. | Agent | Report name | |-------|-------------| @@ -74,9 +63,6 @@ Default agents and their report names (``): | **@test-quality-review-agent** | `test-quality-review` | | **@code-simplicity-review-agent** | `code-simplicity-review` | -**If an agent fails:** note it, continue with the successful agents, and record the failure -in the report header and chat summary so the user knows the review is incomplete. Offer to retry. - ## Step 3 — Consolidate & Present Follow the [review consolidation procedure](references/review-consolidation.md): @@ -126,11 +112,5 @@ brief summary of which findings (by id) were fixed. review is incomplete. - Auto-fix only touches files within the original scope. If a fix needs changes outside scope, flag it instead of silently expanding scope. - -## Important - -- One consolidated report per run. Per-agent raw reports live in `docs/code-review//raw/` - for drill-down and are linked from the consolidated file. -- Reports are untracked working files. Commit or delete them when no longer needed. -- This skill is advisory. It presents findings and lets the user decide what to act on. -- When in doubt about a finding, read its linked raw report for full detail before deciding. +- Reports are untracked working files that survive the run — commit or delete them when no + longer needed. When a finding is ambiguous, its linked raw report carries the full detail. diff --git a/skills/review/references/review-dispatch.md b/skills/review/references/review-dispatch.md new file mode 120000 index 0000000..0ee87b7 --- /dev/null +++ b/skills/review/references/review-dispatch.md @@ -0,0 +1 @@ +../../shared/references/review-dispatch.md \ No newline at end of file diff --git a/skills/shared/references/feature-branch.md b/skills/shared/references/feature-branch.md new file mode 100644 index 0000000..3e29cad --- /dev/null +++ b/skills/shared/references/feature-branch.md @@ -0,0 +1,14 @@ +# Feature Branch Check + +Run before writing any document or code, so work never lands on a base branch. + +```bash +git rev-parse --abbrev-ref HEAD +``` + +- **Already on a feature branch** → continue without prompting. +- **On a base branch** (`main`, `master`, or `develop`) → use **AskUserQuestion** to offer + creating one: `git checkout -b /`, name under 60 characters. `` is + the conventional-commit type for the work (`feat`, `fix`, `refactor`, …). + +A hotfix is the exception: it uses the `hotfix/` prefix, not `fix/`. diff --git a/skills/shared/references/review-dispatch.md b/skills/shared/references/review-dispatch.md new file mode 100644 index 0000000..f30526f --- /dev/null +++ b/skills/shared/references/review-dispatch.md @@ -0,0 +1,27 @@ +# Review Agent Dispatch + +How a skill launches its quality-review agents. The calling skill supplies two things: the +absolute raw-reports directory (``) and the table of agents with their report names. + +## Resolve the paths + +Run `pwd` and let `` be the result — subagents may change directories, so a relative +path is unreliable. Substitute `` into `` before dispatching; never pass a +relative path to an agent. + +## Dispatch + +Run every agent in the skill's table **in parallel**, in a single message. Each agent prompt +carries: + +1. **The scope constraint** — the changed-file list, the specific paths under review, or no + constraint, whichever the calling skill established. +2. **The [review agent instructions](review-agent-instructions.md)**, with `` set to + the resolved absolute directory and `` set to that agent's report name from the + table (a bare stem — the agent writes `/.md`). + +## Handle failures + +An agent failure is non-fatal. Note it, continue with the rest, and record the failure in +both the report header and the chat summary so the user knows the review is incomplete — +a silently halved review reads as a clean one. From 38a09b2d5d6d84ceec14d3c546e11da93c0f7989 Mon Sep 17 00:00:00 2001 From: Dominik Simonik Date: Wed, 7 Oct 2026 13:38:54 +0200 Subject: [PATCH 2/2] refactor: apply prompt-audit findings to agents and skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Second pass over the same surface, run through the claude-api skill's prompt-audit workflow against the Claude 5 generation. The first commit restructured where instructions live; this one fixes the instruction text itself. Under-described (the fix is more text, not less): - Expand four agent descriptions that stated neither what the agent returns nor when not to use it — pr-readiness, best-practices-research, official-docs-research, and user-flow-analysis. These are the four the first commit never touched, since only the other six carried . - Give skills/hotfix a trigger surface. It was the one skill with no trigger phrases at all, having never had a when_to_use field to merge. Dated prompt text: - Drop role inflation that substituted for context ("elite", "seasoned Senior Engineer", "knows all the ins and outs"). Role lines that pair the role with its reason are left alone. - Remove the "Your mission" list in user-flow-analysis that the section headings below it already restate, plus "Be exhaustively thorough" — current models are proactive by default. - Normalize caps emphasis: "MANDATORY Deprecation Check" and four "DO NOT proceed until..." gates. - Fix a drifted duplicate: hotfix capped PR titles at 70 characters, create-pr and conventional-commits at 72. Left alone deliberately: trigger-phrase enumeration in skill descriptions (routing text, and changing it without a trigger eval is guessing), and the YAGNI/testing prohibitions, which encode VGV policy from AGENTS.md. Co-Authored-By: Claude Opus 5 (1M context) --- agents/analysis/user-flow-analysis-agent.md | 17 +++-------------- agents/codebase-review/codebase-review-agent.md | 4 +--- .../quality-review/pr-readiness-review-agent.md | 2 +- .../research/best-practices-research-agent.md | 10 ++++------ agents/research/official-docs-research-agent.md | 4 ++-- skills/brainstorm/SKILL.md | 2 +- skills/create/SKILL.md | 2 +- skills/debrief/SKILL.md | 2 +- skills/hotfix/SKILL.md | 6 +++--- 9 files changed, 17 insertions(+), 32 deletions(-) diff --git a/agents/analysis/user-flow-analysis-agent.md b/agents/analysis/user-flow-analysis-agent.md index bc9abf9..de01cc8 100644 --- a/agents/analysis/user-flow-analysis-agent.md +++ b/agents/analysis/user-flow-analysis-agent.md @@ -1,23 +1,13 @@ --- name: user-flow-analysis-agent skills: [elements-of-style] -description: Analyzes specifications and feature descriptions for user flow completeness and gap identification. Use when a spec, plan, or feature description needs flow analysis, edge case discovery, or requirements validation. +description: Analyzes a specification, plan, or feature description for user-flow completeness — maps the distinct journeys, their decision points and branches, and the states a user can reach. Returns the flows, a gap list organized by category (error handling, validation, auth, persistence, accessibility), and clarifying questions prioritized by whether they block implementation. Use when a spec needs validating before it becomes a plan, or when edge cases are likely under-specified. It analyzes and questions; it does not amend the spec. model: inherit --- # User flow analysis agent -You are an elite User Experience Flow Analyst and Requirements Engineer. Your expertise lies in examining specifications, plans, and feature descriptions through the lens of the end user, identifying every possible user journey, edge case, and interaction pattern. - -**Your mission:** - -1. Map out ALL possible user flows and permutations -2. Identify gaps, ambiguities, and missing specifications -3. Ask clarifying questions about unclear elements -4. Present a comprehensive overview of user journeys -5. Highlight areas that need further definition - -When you receive a specification, plan, or feature description, you will: +You examine specifications, plans, and feature descriptions through the lens of the end user. A spec gets implemented exactly as written, so a journey nobody mapped is a journey nobody builds — that is what makes a gap worth reporting. ## 1: Deep Flow Analysis @@ -114,7 +104,6 @@ For each question, include: **Key principles:** -- **Be exhaustively thorough** - assume the spec will be implemented exactly as written, so every gap matters - **Think like a user** - walk through flows as if you're actually using the feature - **Consider the unhappy paths** - errors, failures, and edge cases are where most gaps hide - **Be specific in questions** - avoid "what about errors?" in favor of "what should happen when the OAuth provider returns a 429 rate limit error?" @@ -122,4 +111,4 @@ For each question, include: - **Use examples liberally** - concrete scenarios make ambiguities clear - **Reference existing patterns** - when available, reference how similar flows work in the codebase -Your goal is to ensure that when implementation begins, developers have a crystal-clear understanding of every user journey, every edge case is accounted for, and no critical questions remain unanswered. Be the advocate for the user's experience and the guardian against ambiguity. +Developers should finish this analysis knowing every journey the spec implies, and every question that still blocks implementation. diff --git a/agents/codebase-review/codebase-review-agent.md b/agents/codebase-review/codebase-review-agent.md index b349604..dc52abf 100644 --- a/agents/codebase-review/codebase-review-agent.md +++ b/agents/codebase-review/codebase-review-agent.md @@ -8,9 +8,7 @@ effort: medium # Codebase Review Agent -You are a seasoned Senior Engineer with expertise in software architecture and engineering. You also have a strong understanding of our [Very Good Engineering](https://engineering.verygood.ventures) practices, as well as software architecture, design patterns, and industry best practices. - -Your role is to conduct a thorough review of the given codebase, ensure code quality standards are met, and validate that the codebase uses consistently the same patterns. +You review a codebase against [Very Good Engineering](https://engineering.verygood.ventures) practices: whether quality standards are met, and whether the same patterns are applied consistently across it. ## Phase 0 — Detect stack and discover conventions diff --git a/agents/quality-review/pr-readiness-review-agent.md b/agents/quality-review/pr-readiness-review-agent.md index dbce837..ee51c6f 100644 --- a/agents/quality-review/pr-readiness-review-agent.md +++ b/agents/quality-review/pr-readiness-review-agent.md @@ -1,6 +1,6 @@ --- name: pr-readiness-review-agent -description: Checks PR readiness — formatting, static analysis, debug artifacts, and commit hygiene — to catch mechanical issues before opening a pull request. +description: Checks whether a branch is mechanically ready to open as a pull request — formatter and linter clean, no debug artifacts (stray print/console statements, commented-out code), no committed secrets or large binaries, and commit messages that follow the project's convention. Returns findings graded Critical, Important, or Suggestion, each with a file:line and a concrete fix. Use after the code is written and before opening a PR. It does not assess correctness, architecture, or test quality — the other review agents cover those. model: haiku --- diff --git a/agents/research/best-practices-research-agent.md b/agents/research/best-practices-research-agent.md index d1ed820..f4e5fc8 100644 --- a/agents/research/best-practices-research-agent.md +++ b/agents/research/best-practices-research-agent.md @@ -1,14 +1,12 @@ --- name: best-practices-research-agent -description: Researches and synthesizes best practices for the project's technology stack, following first VGV conventions and the project's CLAUDE.md, then official language and framework documentation, and finally other industry standards. +description: Researches and synthesizes best practices for the project's technology stack, consulting sources in a fixed order — VGV conventions and the project's CLAUDE.md first, then official language and framework documentation, then wider industry standards — and naming which tier each recommendation came from. Checks external APIs, SDKs, and OAuth flows for deprecation before recommending them. Returns actionable guidance with code patterns and citations, scoped to the task. Use when a plan touches unfamiliar technology or a high-risk area such as security, payments, external APIs, or personal data. It researches; it does not write implementation code. model: sonnet --- # Best practices research agent -You are a software engineering expert, with a strong focus on best practices, elegant solutions, and scalable architecture. - -Your mission is to provide comprehensive, actionable guidance based on established standards. You always prioritize recommendations and guidance from: (1) VGV conventions and the project's CLAUDE.md, (2) official language and framework documentation, and (3) industry standards and known successful implementations. +You provide actionable guidance grounded in established standards, prioritizing sources in this order: (1) VGV conventions and the project's CLAUDE.md, (2) official language and framework documentation, (3) industry standards and known successful implementations. Name which tier a recommendation came from — a project convention and a blog post are not the same evidence. ## Research steps to follow in order @@ -33,9 +31,9 @@ Before doing any external research, check that local knowledge might exist: - Scan existing code patterns for established practices - If VGV conventions and project patterns provide comprehensive guidance, summarize and deliver - If conventions provide partial guidance, note what's covered, proceed to Phase 1.5 and Phase 2 for gaps - - If no relevant conventions found, proceed to `1.1 MANDATORY Deprecation Check` and `2. Online research (if needed)` + - If no relevant conventions found, proceed to `1.1 Deprecation check` and `2. Online research (if needed)` -### 1.1: MANDATORY Deprecation Check (for external APIs/services) +### 1.1: Deprecation check (for external APIs/services) **Before recommending any external API, OAuth flow, SDK, or third-party service:** diff --git a/agents/research/official-docs-research-agent.md b/agents/research/official-docs-research-agent.md index 76fe78d..88b0b57 100644 --- a/agents/research/official-docs-research-agent.md +++ b/agents/research/official-docs-research-agent.md @@ -1,12 +1,12 @@ --- name: official-docs-research-agent -description: Gathers comprehensive documentation and best practices for frameworks, libraries, or dependencies. Use when you need official docs, version-specific constraints, or implementation patterns. +description: Gathers and synthesizes official documentation for a specific framework, library, SDK, or language — API surface, version-specific constraints, migration notes, and the implementation patterns the maintainers themselves recommend. Returns the relevant excerpts with source URLs and the version each applies to, rather than a general summary. Use when a plan depends on a dependency's exact behavior, or when a version constraint could change the approach. It reads official sources only — for community or cross-stack practice, use best-practices-research-agent. model: sonnet --- # Official docs research agent -You are an expert that knows all the ins and outs of the official documentation for the framework/SDK/library/programming language in scope. Your expertise lies in efficiently collecting, analyzing, and synthesizing documentation from multiple sources to provide developers with the exact information they need. +You collect and synthesize official documentation — the maintainers' own docs, API references, and migration guides — into the exact information the task needs, with the version each claim applies to. **Core responsibilities:** diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index 5869a0b..d209f49 100644 --- a/skills/brainstorm/SKILL.md +++ b/skills/brainstorm/SKILL.md @@ -18,7 +18,7 @@ Clarify **WHAT** to build before diving into **HOW** to build it. Explore user i **If the feature description above is empty, ask the user**: "What feature would you like to brainstorm? Describe the idea, problem or feature you are thinking about." -DO NOT proceed until you have a description from the user. +Do not proceed until you have a description from the user. ## Execution flow diff --git a/skills/create/SKILL.md b/skills/create/SKILL.md index 83f6303..e28838c 100644 --- a/skills/create/SKILL.md +++ b/skills/create/SKILL.md @@ -23,7 +23,7 @@ Route project creation to the right companion plugin. Wingspan does not scaffold - **Question:** "What kind of project would you like to create?" - **Options:** Build the option list from the discovered companion plugins' descriptions, plus "Other" as the last option. -DO NOT proceed until you have a project description. +Do not proceed until you have a project description. ## Step 1: Scan recommendation files diff --git a/skills/debrief/SKILL.md b/skills/debrief/SKILL.md index c247e23..2ed2fba 100644 --- a/skills/debrief/SKILL.md +++ b/skills/debrief/SKILL.md @@ -21,7 +21,7 @@ Produce a structured, blameless debrief document after an incident, failed relea **If the incident context above is empty, ask the user**: "What incident would you like to debrief? Describe what happened, link to relevant PRs/commits, or paste error logs." -DO NOT proceed until you have a description from the user. +Do not proceed until you have a description from the user. ## Execution Flow diff --git a/skills/hotfix/SKILL.md b/skills/hotfix/SKILL.md index 688112b..af760e1 100644 --- a/skills/hotfix/SKILL.md +++ b/skills/hotfix/SKILL.md @@ -1,7 +1,7 @@ --- name: hotfix user-invocable: true -description: Applies a minimal, targeted fix for emergency bugs — enforces review and testing without brainstorm or planning phases. +description: Applies a minimal, targeted fix for emergency bugs — enforces review and testing without brainstorm or planning phases. Use when the user says "hotfix", "emergency fix", "production is broken", "urgent bug", or needs a fix shipped fast without the full plan-and-build cycle. effort: high argument-hint: bug description, issue link, or error message allowed-tools: Bash(rm -rf docs/hotfix-review/) @@ -18,7 +18,7 @@ Apply a minimal, targeted fix fast. No brainstorm document, no plan document — **If the bug description above is empty, ask the user**: "What's the bug? Paste a description, issue link, or error message." -DO NOT proceed until you have a bug description. +Do not proceed until you have a bug description. ## Phase 0 — Triage @@ -133,7 +133,7 @@ fix: Bug: ``` -Push the branch and create a PR. **Title**: `fix: ` (under 70 chars). **Body**: Use the [PR template](references/pr-template.md). +Push the branch and create a PR. **Title**: `fix: ` (max 72 characters, matching `/create-pr`). **Body**: Use the [PR template](references/pr-template.md). ### Post-Ship