Skip to content

Commit 7a8f449

Browse files
omartinmaomartinma
authored
Merge branch 'main' into feat/205
2 parents 7965f92 + 559f5ee commit 7a8f449

4 files changed

Lines changed: 259 additions & 14 deletions

File tree

‎.github/ISSUE_TEMPLATE/refactor.yaml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Refactor
2+
description: Suggest a code change that neither fixes a bug nor adds a feature.
3+
title: "refactor: "
4+
labels: ["refactor"]
5+
body:
6+
- type: textarea
7+
id: description
8+
attributes:
9+
label: Description
10+
description: A clear description of what needs to be refactored and why.
11+
validations:
12+
required: true
13+
- type: textarea
14+
id: requirements
15+
attributes:
16+
label: Requirements
17+
description: >
18+
What must be true for this change to be complete?
19+
Consider markdown lint, spell check, and structure validation.
20+
validations:
21+
required: false
22+
- type: textarea
23+
id: additional-context
24+
attributes:
25+
label: Additional Context
26+
description: Any other context about the request.
27+
validations:
28+
required: false

‎CODE_OF_CONDUCT.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, sex characteristics, gender identity and expression,
9+
level of experience, education, socio-economic status, nationality, personal
10+
appearance, race, religion, or sexual identity and orientation.
11+
12+
## Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
- Using welcoming and inclusive language
18+
- Being respectful of differing viewpoints and experiences
19+
- Gracefully accepting constructive criticism
20+
- Focusing on what is best for the community
21+
- Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
- The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
- Trolling, insulting/derogatory comments, and personal or political attacks
28+
- Public or private harassment
29+
- Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
- Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
## Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or
41+
reject comments, commits, code, wiki edits, issues, and other contributions
42+
that are not aligned to this Code of Conduct, or to ban temporarily or
43+
permanently any contributor for other behaviors that they deem inappropriate,
44+
threatening, offensive, or harmful.
45+
46+
## Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
## Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting the project team at <hello@verygood.ventures>. All
59+
complaints will be reviewed and investigated and will result in a response that
60+
is deemed necessary and appropriate to the circumstances. The project team is
61+
obligated to maintain confidentiality with regard to the reporter of an incident.
62+
Further details of specific enforcement policies may be posted separately.
63+
64+
Project maintainers who do not follow or enforce the Code of Conduct in good
65+
faith may face temporary or permanent repercussions as determined by other
66+
members of the project's leadership.
67+
68+
## Attribution
69+
70+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71+
available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
72+
73+
[homepage]: https://www.contributor-covenant.org
74+
75+
For answers to common questions about this code of conduct, see
76+
<https://www.contributor-covenant.org/faq/>

‎CONTRIBUTING.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,103 @@ Keep inline bash when:
165165
- Write errors to stderr, data to stdout
166166
- Exit 1 on failure with a descriptive message
167167

168+
## Testing Locally
169+
170+
Editing a skill or hook and pushing straight to a PR only tells you the files
171+
are valid, not that they work correctly. Load your working copy into a real Claude Code
172+
session and exercise it before you commit.
173+
174+
### Prerequisites
175+
176+
- **Claude Code CLI** installed (`npm install -g @anthropic-ai/claude-code`).
177+
- **jq** on your `PATH` — the recommendation hook needs it and skips silently without it.
178+
179+
### Load your local copy
180+
181+
From the repository root, launch Claude Code pointed at this directory:
182+
183+
```bash
184+
claude --plugin-dir .
185+
```
186+
187+
`--plugin-dir` loads the plugin for that session only, needs no install or
188+
marketplace, and overrides any marketplace-installed copy of the same plugin.
189+
`${CLAUDE_PLUGIN_ROOT}` (used in `hooks/hooks.json`) resolves to the directory
190+
you pass, so the hook script paths resolve correctly.
191+
192+
### Verify each component loaded
193+
194+
| Component | How to verify |
195+
| --------- | ------------- |
196+
| **Skills** | Run `/help`. Skills appear namespaced as `/vgv-wingspan:<skill>` (e.g. `/vgv-wingspan:brainstorm`). Invoke one to confirm it triggers. |
197+
| **Agents** | Ask Claude to run one by name (e.g. "review this with the vgv-review-agent") and confirm it dispatches. |
198+
| **Hooks** | In a project with a detectable type (e.g. a Flutter app), have Claude `Read` a file and confirm the plugin recommendation fires. |
199+
200+
The recommendation hook writes a marker file (`/tmp/wingspan-recommend-plugins-<hash>`)
201+
after it emits a recommendation, suppressing repeats for the session. Delete the
202+
marker to re-test:
203+
204+
```bash
205+
rm -f /tmp/wingspan-recommend-plugins-*
206+
```
207+
208+
### Iterate on changes
209+
210+
After editing a `SKILL.md` or `hooks/hooks.json`, **restart the
211+
`claude --plugin-dir .` session** to guarantee the change is picked up. Changes
212+
to `.claude-plugin/plugin.json` always require a restart. Edits to the hook
213+
`.sh` scripts take effect on the next matching tool call with no restart, since
214+
each hook runs the script fresh.
215+
216+
### Rehearse the real install (optional)
217+
218+
To mimic the marketplace install flow without pushing anything, register a
219+
throwaway local marketplace. Create `.claude-plugin/marketplace.json` in a temp
220+
directory with an **absolute** path to this repo:
221+
222+
```jsonc
223+
// /tmp/vgv-test-marketplace/.claude-plugin/marketplace.json
224+
{
225+
"plugins": [
226+
{
227+
"name": "vgv-wingspan",
228+
"source": {
229+
"type": "directory",
230+
"path": "/ABSOLUTE/path/to/wingspan"
231+
}
232+
}
233+
]
234+
}
235+
```
236+
237+
Then, inside a session:
238+
239+
```text
240+
/plugin marketplace add /tmp/vgv-test-marketplace
241+
/plugin install vgv-wingspan
242+
```
243+
244+
### Validate before you push
245+
246+
Run the same check CI runs, from the repository root:
247+
248+
```bash
249+
claude plugin validate .
250+
```
251+
252+
This validates the manifest, skill frontmatter, hook JSON, and file references.
253+
It is static, so it confirms structure but does not replace the live checks above.
254+
255+
### Troubleshooting
256+
257+
| Symptom | Likely cause | Fix |
258+
| ------- | ------------ | --- |
259+
| Skill missing from `/help` | Invalid frontmatter | Run `claude plugin validate .` and fix the reported error |
260+
| Hook never fires | `jq` not installed, marker file left over, or script lacks `+x` / a shebang | Install `jq`; remove the `/tmp/wingspan-recommend-plugins-*` marker; `chmod +x` the script |
261+
| Skill references a shared file that 404s | Symlink missing or points outside the skill directory | Recreate the symlink per [Sharing content across skills](#sharing-content-across-skills) |
262+
| `${CLAUDE_PLUGIN_ROOT}` not resolving | Session not launched via `--plugin-dir` (or restart pending) | Restart with `claude --plugin-dir .` from the repo root |
263+
| Local marketplace won't install | `source.path` is relative | Use an absolute path in `marketplace.json` |
264+
168265
## CI Checks
169266

170267
Every pull request runs the following checks automatically:

‎README.md‎

Lines changed: 58 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
# VGV Wingspan
22

3-
🦋 AI-assisted workflows that follow Very Good Ventures best practices and standards.
3+
[![Very Good Ventures][logo_white]][very_good_ventures_link_dark]
4+
[![Very Good Ventures][logo_black]][very_good_ventures_link_light]
5+
6+
🦋 AI-assisted workflows that follow [Very Good Ventures][vgv_link] best practices and standards.
7+
8+
Developed with 💙 by [Very Good Ventures][vgv_link] 🦄
49

510
![wingspan logo by very good ventures in blue](./assets/wingspan-logo.jpeg)
611

@@ -86,16 +91,55 @@ Wingspan operates at a higher level, orchestrating agentic workflows across the
8691

8792
| Skill | Command | Description |
8893
|-------|---------|-------------|
89-
| **Brainstorm** | `/brainstorm <feature or idea>` | Explore requirements and approaches through collaborative dialogue |
90-
| **Refine Approach** | `/refine-approach` | Review and refine brainstorms or plans before proceeding |
91-
| **Plan** | `/plan <feature, bug fix, or improvement>` | Transform brainstorm output into a structured implementation plan |
92-
| **Plan Technical Review** | `/plan-technical-review` | Validate that a plan meets requirements and follows best practices |
93-
| **Build** | `/build <plan file path>` | Execute a plan — write code and tests, run quality review, ship a PR |
94-
| **Review** | `/review [path]` | Run quality review agents on demand — assess code quality and identify issues |
95-
| **Hotfix** | `/hotfix <bug description>` | Apply a minimal, targeted fix for emergency bugs — enforces review and testing without brainstorm or planning |
96-
| **Create Branch** | `/create-branch` | Set up a workspace (branch or worktree) before writing artifacts |
97-
| **Create** | `/create <what to create>` | Scaffold a new project by routing to the right companion plugin |
98-
| **Create Commit** | `/create-commit` | Stage and commit changes using conventional commit messages |
99-
| **Create PR** | `/create-pr` | Validate (formatter, linter, tests, and CI checks), stage, commit, push, and open a pull request on the project's Git hosting platform — aborts on any failure |
100-
| **Rebase** | `/rebase` | Rebase the current feature branch onto the base branch to stay up-to-date |
101-
| **Debrief** | `/debrief <incident or context>` | Produce a structured post-incident analysis — timeline, root cause, and actionable follow-ups |
94+
| [**Brainstorm**](skills/brainstorm/SKILL.md) | `/brainstorm <feature or idea>` | Explore requirements and approaches through collaborative dialogue |
95+
| [**Refine Approach**](skills/refine-approach/SKILL.md) | `/refine-approach` | Review and refine brainstorms or plans before proceeding |
96+
| [**Plan**](skills/plan/SKILL.md) | `/plan <feature, bug fix, or improvement>` | Transform brainstorm output into a structured implementation plan |
97+
| [**Plan Technical Review**](skills/plan-technical-review/SKILL.md) | `/plan-technical-review` | Validate that a plan meets requirements and follows best practices |
98+
| [**Build**](skills/build/SKILL.md) | `/build <plan file path>` | Execute a plan — write code and tests, run quality review, ship a PR |
99+
| [**Review**](skills/review/SKILL.md) | `/review [path]` | Run quality review agents on demand — assess code quality and identify issues |
100+
| [**Hotfix**](skills/hotfix/SKILL.md) | `/hotfix <bug description>` | Apply a minimal, targeted fix for emergency bugs — enforces review and testing without brainstorm or planning |
101+
| [**Create Branch**](skills/create-branch/SKILL.md) | `/create-branch` | Set up a workspace (branch or worktree) before writing artifacts |
102+
| [**Create**](skills/create/SKILL.md) | `/create <what to create>` | Scaffold a new project by routing to the right companion plugin |
103+
| [**Create Commit**](skills/create-commit/SKILL.md) | `/create-commit` | Stage and commit changes using conventional commit messages |
104+
| [**Create PR**](skills/create-pr/SKILL.md) | `/create-pr` | Validate (formatter, linter, tests, and CI checks), stage, commit, push, and open a pull request on the project's Git hosting platform — aborts on any failure |
105+
| [**Rebase**](skills/rebase/SKILL.md) | `/rebase` | Rebase the current feature branch onto the base branch to stay up-to-date |
106+
| [**Debrief**](skills/debrief/SKILL.md) | `/debrief <incident or context>` | Produce a structured post-incident analysis — timeline, root cause, and actionable follow-ups |
107+
108+
## Agents
109+
110+
Wingspan ships subagents that Claude Code dispatches as isolated, specialized reviewers. Unlike skills, agents are **not** invoked as slash commands — the workflow skills dispatch them automatically, or you can ask Claude to run one by name (e.g. "review my changes with the vgv-review-agent").
111+
112+
| Agent | Description |
113+
| ----- | ----------- |
114+
| [**VGV Review**](agents/codebase-review/vgv-review-agent.md) | Reviews code against Very Good Ventures engineering standards — architecture, state management conventions, testing quality, and code simplicity |
115+
| [**Code Simplicity Review**](agents/codebase-review/code-simplicity-review-agent.md) | Final review pass to ensure code is as simple and minimal as possible — identifies YAGNI violations and simplification opportunities |
116+
| [**Codebase Review**](agents/codebase-review/codebase-review-agent.md) | Conducts a thorough review of the codebase — structure, conventions, and consistent pattern usage |
117+
| [**Architecture Review**](agents/quality-review/architecture-review-agent.md) | Validates project architecture post-implementation — layer separation, dependency direction, and package structure |
118+
| [**Test Quality Review**](agents/quality-review/test-quality-review-agent.md) | Reviews test coverage and quality — verifies every testable unit has proper tests following VGV conventions |
119+
| [**PR Readiness Review**](agents/quality-review/pr-readiness-review-agent.md) | Checks formatting, static analysis, debug artifacts, and commit hygiene before a pull request opens |
120+
| [**Plan Splitting**](agents/analysis/plan-splitting-agent.md) | Analyzes implementation plans for scope and recommends splitting large plans into independently-mergeable PRs |
121+
| [**User Flow Analysis**](agents/analysis/user-flow-analysis-agent.md) | Analyzes specs and feature descriptions for flow completeness, edge cases, and requirement gaps |
122+
| [**Best Practices Research**](agents/research/best-practices-research-agent.md) | Researches best practices for the project's technology stack — VGV conventions first, then official docs and industry standards |
123+
| [**Official Docs Research**](agents/research/official-docs-research-agent.md) | Gathers documentation for frameworks, libraries, or dependencies — official docs, version constraints, and implementation patterns |
124+
125+
## Hooks
126+
127+
Wingspan includes a `PreToolUse` hook that detects your project type and recommends companion plugins you haven't installed yet.
128+
129+
| Hook | Trigger | Behavior |
130+
| ---- | ------- | -------- |
131+
| **Recommend Plugins** (`recommend-plugins.sh`) | PreToolUse (`Read`/`Glob`/`Grep`) | Scans detection rules in `hooks/recommendations/`, recommends missing companion plugins once per session; non-blocking |
132+
133+
### Prerequisites
134+
135+
- **jq** — used to parse recommendation rules; the hook is skipped gracefully if `jq` is not installed
136+
137+
## Contributing
138+
139+
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add or improve skills, test your changes locally, and open a pull request. All contributors are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
140+
141+
[vgv_link]: https://verygood.ventures
142+
[very_good_ventures_link_dark]: https://verygood.ventures#gh-dark-mode-only
143+
[very_good_ventures_link_light]: https://verygood.ventures#gh-light-mode-only
144+
[logo_black]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_black.png#gh-light-mode-only
145+
[logo_white]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_white.png#gh-dark-mode-only

0 commit comments

Comments
 (0)