diff --git a/README.md b/README.md index 43f05d6..29119cc 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Supported agents: **Claude Code**, **Augment**, **Codex**, **Junie**, **Roo Code - **Deferred critical comments**: Classifies critical or larger-scope comments (security gaps, missing features, cross-file refactors) and handles them after all normal comments are done. For each deferred item you pick the workflow: SDD, Brainstorming, plan mode, just-do-it, or skip. - **Reply/Resolve preference**: One prompt per project decides whether the skill may post replies and resolve threads on your behalf (`a` post & resolve / `b` post only / `c` none). Applied uniformly across normal, deferred, and no-code-change paths. - **Configurable verification**: Runs project-defined lint, test, and analysis commands from `CLAUDE.md` (or `AGENTS.md` as fallback). +- **Graphify-aware**: If a `graphify` skill is available in the running agent, the skill is required to use it for understanding code, mapping cross-file relationships, and design decisions (Step 0). If Graphify is absent, the skill proceeds normally. - **Language-agnostic**: Works with any programming language or framework. ## Supported Platforms @@ -27,6 +28,14 @@ Supported agents: **Claude Code**, **Augment**, **Codex**, **Junie**, **Roo Code For platforms with two paths the skill prompts on first use. The choice is persisted in project memory and skipped on subsequent runs. +## Architecture + +A single source (`core/` + `adapters//`) is compiled into per-agent variants +(`skills/`, `dist/`, `plugins/`) by `scripts/build.sh`. Generated artifacts are committed +automatically after merge by the release workflow. For the full picture — source vs. +generated files, per-agent `plugin.json` differences, the build, and the CI/CD release +flow — see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). + ## Installation ### Claude Code diff --git a/adapters/augment/snippets/graphify-availability.md b/adapters/augment/snippets/graphify-availability.md new file mode 100644 index 0000000..b7b2a1b --- /dev/null +++ b/adapters/augment/snippets/graphify-availability.md @@ -0,0 +1 @@ +These harnesses do not expose a skills registry. Treat Graphify as available only if the project clearly ships it (e.g. a `graphify` skill/command file under the project's skills directory or an entry in the agent config). If you cannot positively confirm it, treat Graphify as unavailable and proceed without it. diff --git a/adapters/claude/snippets/graphify-availability.md b/adapters/claude/snippets/graphify-availability.md new file mode 100644 index 0000000..2e05ce0 --- /dev/null +++ b/adapters/claude/snippets/graphify-availability.md @@ -0,0 +1 @@ +Check the list of available skills surfaced by the harness for a `graphify` skill (it may appear as `graphify` or a plugin-namespaced `:graphify`). If present, Graphify is available; invoke it via the Skill tool when required below. diff --git a/adapters/codex/snippets/graphify-availability.md b/adapters/codex/snippets/graphify-availability.md new file mode 100644 index 0000000..b7b2a1b --- /dev/null +++ b/adapters/codex/snippets/graphify-availability.md @@ -0,0 +1 @@ +These harnesses do not expose a skills registry. Treat Graphify as available only if the project clearly ships it (e.g. a `graphify` skill/command file under the project's skills directory or an entry in the agent config). If you cannot positively confirm it, treat Graphify as unavailable and proceed without it. diff --git a/adapters/junie/snippets/graphify-availability.md b/adapters/junie/snippets/graphify-availability.md new file mode 100644 index 0000000..b7b2a1b --- /dev/null +++ b/adapters/junie/snippets/graphify-availability.md @@ -0,0 +1 @@ +These harnesses do not expose a skills registry. Treat Graphify as available only if the project clearly ships it (e.g. a `graphify` skill/command file under the project's skills directory or an entry in the agent config). If you cannot positively confirm it, treat Graphify as unavailable and proceed without it. diff --git a/adapters/roo/snippets/graphify-availability.md b/adapters/roo/snippets/graphify-availability.md new file mode 100644 index 0000000..b7b2a1b --- /dev/null +++ b/adapters/roo/snippets/graphify-availability.md @@ -0,0 +1 @@ +These harnesses do not expose a skills registry. Treat Graphify as available only if the project clearly ships it (e.g. a `graphify` skill/command file under the project's skills directory or an entry in the agent config). If you cannot positively confirm it, treat Graphify as unavailable and proceed without it. diff --git a/core/kernel.md b/core/kernel.md index 7c521e8..0e49ab1 100644 --- a/core/kernel.md +++ b/core/kernel.md @@ -1,3 +1,19 @@ +## Step 0: Graphify Availability (mandatory if present) + +Before anything else, check whether the **Graphify** skill is available in the running agent for this project. + + + +If Graphify **is** available, using it is **mandatory** for this run. Wherever a later step requires understanding code, mapping relationships across files, or making a design decision, you MUST first run Graphify on the relevant input (the affected file(s), the PR/MR diff, or the surrounding module) and use the resulting knowledge graph to inform your work. This applies in particular to: + +- **Step 4** — understanding each comment in the context of the surrounding code. +- **Step 4b** — every deferred item: build the graph for the item's scope before choosing and executing a design route. +- **Step 6** — self-review: graph the diff to check cross-file impact. + +If Graphify is **not** available, proceed normally — do not block on it. + +Record availability as a transient session fact — do NOT persist it; skill availability can change between sessions. + ## Step 1: Platform Detection & CLI Verification ### 1.1 Check Memory @@ -137,7 +153,7 @@ When a comment is unclear, ask **one** short clarifying question. Before asking, Then work through each task sequentially: 1. **Read the affected file** at the referenced location -2. **Understand the comment** in the context of the surrounding code +2. **Understand the comment** in the context of the surrounding code (if Graphify is available per Step 0, graph the affected file(s) first and use the result to understand the surrounding code) 3. If the comment is marked `(outdated)`, check whether the feedback is still relevant before acting 4. **If unclear**: Ask the user what exactly is expected. 5. **Implement the change** according to the reviewer's feedback @@ -156,6 +172,8 @@ Otherwise announce: "Now handling N deferred items." Process items strictly in t For each deferred item: +0. If Graphify is available (Step 0), build the knowledge graph for this item's scope first and use it to inform the route choice and execution below. + 1. Detect which design skills are visible to the running agent: @@ -209,6 +227,8 @@ Review all changes made: git diff ``` +If Graphify is available (Step 0), graph the diff and use the result to check cross-file impact and relationships before the checks below. + Check for: ### Reusability diff --git a/dist/augment/skills/resolve-comments/SKILL.md b/dist/augment/skills/resolve-comments/SKILL.md index 13d5280..6cea10a 100644 --- a/dist/augment/skills/resolve-comments/SKILL.md +++ b/dist/augment/skills/resolve-comments/SKILL.md @@ -9,6 +9,22 @@ Work through all unresolved review comments from a pull request or merge request > This skill activates implicitly when its description matches your request. You can also reference it explicitly by name. +## Step 0: Graphify Availability (mandatory if present) + +Before anything else, check whether the **Graphify** skill is available in the running agent for this project. + +These harnesses do not expose a skills registry. Treat Graphify as available only if the project clearly ships it (e.g. a `graphify` skill/command file under the project's skills directory or an entry in the agent config). If you cannot positively confirm it, treat Graphify as unavailable and proceed without it. + +If Graphify **is** available, using it is **mandatory** for this run. Wherever a later step requires understanding code, mapping relationships across files, or making a design decision, you MUST first run Graphify on the relevant input (the affected file(s), the PR/MR diff, or the surrounding module) and use the resulting knowledge graph to inform your work. This applies in particular to: + +- **Step 4** — understanding each comment in the context of the surrounding code. +- **Step 4b** — every deferred item: build the graph for the item's scope before choosing and executing a design route. +- **Step 6** — self-review: graph the diff to check cross-file impact. + +If Graphify is **not** available, proceed normally — do not block on it. + +Record availability as a transient session fact — do NOT persist it; skill availability can change between sessions. + ## Step 1: Platform Detection & CLI Verification ### 1.1 Check Memory @@ -190,7 +206,7 @@ When a comment is unclear, ask **one** short clarifying question. Before asking, Then work through each task sequentially: 1. **Read the affected file** at the referenced location -2. **Understand the comment** in the context of the surrounding code +2. **Understand the comment** in the context of the surrounding code (if Graphify is available per Step 0, graph the affected file(s) first and use the result to understand the surrounding code) 3. If the comment is marked `(outdated)`, check whether the feedback is still relevant before acting 4. **If unclear**: Ask the user what exactly is expected. Ask the user directly in chat with the listed options. 5. **Implement the change** according to the reviewer's feedback @@ -209,6 +225,8 @@ Otherwise announce: "Now handling N deferred items." Process items strictly in t For each deferred item: +0. If Graphify is available (Step 0), build the knowledge graph for this item's scope first and use it to inform the route choice and execution below. + 1. Detect which design skills are visible to the running agent: These harnesses do not currently expose a skills registry; assume `[s]` and `[b]` are unavailable. Show them marked unavailable; allow the user to type a path to a local skill file if they want to invoke one manually. Record this as a transient session fact — do NOT persist it. @@ -262,6 +280,8 @@ Review all changes made: git diff ``` +If Graphify is available (Step 0), graph the diff and use the result to check cross-file impact and relationships before the checks below. + Check for: ### Reusability diff --git a/dist/codex/skills/resolve-comments/SKILL.md b/dist/codex/skills/resolve-comments/SKILL.md index 7e32016..e7a6afc 100644 --- a/dist/codex/skills/resolve-comments/SKILL.md +++ b/dist/codex/skills/resolve-comments/SKILL.md @@ -9,6 +9,22 @@ Work through all unresolved review comments from a pull request or merge request > Invoke this skill via `$resolve-comments` or the `/skills` command. This skill is stateless: platform detection runs on every invocation. +## Step 0: Graphify Availability (mandatory if present) + +Before anything else, check whether the **Graphify** skill is available in the running agent for this project. + +These harnesses do not expose a skills registry. Treat Graphify as available only if the project clearly ships it (e.g. a `graphify` skill/command file under the project's skills directory or an entry in the agent config). If you cannot positively confirm it, treat Graphify as unavailable and proceed without it. + +If Graphify **is** available, using it is **mandatory** for this run. Wherever a later step requires understanding code, mapping relationships across files, or making a design decision, you MUST first run Graphify on the relevant input (the affected file(s), the PR/MR diff, or the surrounding module) and use the resulting knowledge graph to inform your work. This applies in particular to: + +- **Step 4** — understanding each comment in the context of the surrounding code. +- **Step 4b** — every deferred item: build the graph for the item's scope before choosing and executing a design route. +- **Step 6** — self-review: graph the diff to check cross-file impact. + +If Graphify is **not** available, proceed normally — do not block on it. + +Record availability as a transient session fact — do NOT persist it; skill availability can change between sessions. + ## Step 1: Platform Detection & CLI Verification ### 1.1 Check Memory @@ -175,7 +191,7 @@ When a comment is unclear, ask **one** short clarifying question. Before asking, Then work through each task sequentially: 1. **Read the affected file** at the referenced location -2. **Understand the comment** in the context of the surrounding code +2. **Understand the comment** in the context of the surrounding code (if Graphify is available per Step 0, graph the affected file(s) first and use the result to understand the surrounding code) 3. If the comment is marked `(outdated)`, check whether the feedback is still relevant before acting 4. **If unclear**: Ask the user what exactly is expected. Ask the user directly in chat with the listed options. 5. **Implement the change** according to the reviewer's feedback @@ -194,6 +210,8 @@ Otherwise announce: "Now handling N deferred items." Process items strictly in t For each deferred item: +0. If Graphify is available (Step 0), build the knowledge graph for this item's scope first and use it to inform the route choice and execution below. + 1. Detect which design skills are visible to the running agent: These harnesses do not currently expose a skills registry; assume `[s]` and `[b]` are unavailable. Show them marked unavailable; allow the user to type a path to a local skill file if they want to invoke one manually. Record this as a transient session fact — do NOT persist it. @@ -247,6 +265,8 @@ Review all changes made: git diff ``` +If Graphify is available (Step 0), graph the diff and use the result to check cross-file impact and relationships before the checks below. + Check for: ### Reusability diff --git a/dist/junie/.junie/skills/resolve-comments/SKILL.md b/dist/junie/.junie/skills/resolve-comments/SKILL.md index c0234fe..d04b986 100644 --- a/dist/junie/.junie/skills/resolve-comments/SKILL.md +++ b/dist/junie/.junie/skills/resolve-comments/SKILL.md @@ -9,6 +9,22 @@ Work through all unresolved review comments from a pull request or merge request > Junie activates this skill when its description matches your task. +## Step 0: Graphify Availability (mandatory if present) + +Before anything else, check whether the **Graphify** skill is available in the running agent for this project. + +These harnesses do not expose a skills registry. Treat Graphify as available only if the project clearly ships it (e.g. a `graphify` skill/command file under the project's skills directory or an entry in the agent config). If you cannot positively confirm it, treat Graphify as unavailable and proceed without it. + +If Graphify **is** available, using it is **mandatory** for this run. Wherever a later step requires understanding code, mapping relationships across files, or making a design decision, you MUST first run Graphify on the relevant input (the affected file(s), the PR/MR diff, or the surrounding module) and use the resulting knowledge graph to inform your work. This applies in particular to: + +- **Step 4** — understanding each comment in the context of the surrounding code. +- **Step 4b** — every deferred item: build the graph for the item's scope before choosing and executing a design route. +- **Step 6** — self-review: graph the diff to check cross-file impact. + +If Graphify is **not** available, proceed normally — do not block on it. + +Record availability as a transient session fact — do NOT persist it; skill availability can change between sessions. + ## Step 1: Platform Detection & CLI Verification ### 1.1 Check Memory @@ -190,7 +206,7 @@ When a comment is unclear, ask **one** short clarifying question. Before asking, Then work through each task sequentially: 1. **Read the affected file** at the referenced location -2. **Understand the comment** in the context of the surrounding code +2. **Understand the comment** in the context of the surrounding code (if Graphify is available per Step 0, graph the affected file(s) first and use the result to understand the surrounding code) 3. If the comment is marked `(outdated)`, check whether the feedback is still relevant before acting 4. **If unclear**: Ask the user what exactly is expected. Ask the user directly in chat with the listed options. 5. **Implement the change** according to the reviewer's feedback @@ -209,6 +225,8 @@ Otherwise announce: "Now handling N deferred items." Process items strictly in t For each deferred item: +0. If Graphify is available (Step 0), build the knowledge graph for this item's scope first and use it to inform the route choice and execution below. + 1. Detect which design skills are visible to the running agent: These harnesses do not currently expose a skills registry; assume `[s]` and `[b]` are unavailable. Show them marked unavailable; allow the user to type a path to a local skill file if they want to invoke one manually. Record this as a transient session fact — do NOT persist it. @@ -262,6 +280,8 @@ Review all changes made: git diff ``` +If Graphify is available (Step 0), graph the diff and use the result to check cross-file impact and relationships before the checks below. + Check for: ### Reusability diff --git a/dist/roo/.roo/skills/resolve-comments/SKILL.md b/dist/roo/.roo/skills/resolve-comments/SKILL.md index 8a83038..0a36a35 100644 --- a/dist/roo/.roo/skills/resolve-comments/SKILL.md +++ b/dist/roo/.roo/skills/resolve-comments/SKILL.md @@ -9,6 +9,22 @@ Work through all unresolved review comments from a pull request or merge request > Roo loads this skill on demand when your request matches the description above. +## Step 0: Graphify Availability (mandatory if present) + +Before anything else, check whether the **Graphify** skill is available in the running agent for this project. + +These harnesses do not expose a skills registry. Treat Graphify as available only if the project clearly ships it (e.g. a `graphify` skill/command file under the project's skills directory or an entry in the agent config). If you cannot positively confirm it, treat Graphify as unavailable and proceed without it. + +If Graphify **is** available, using it is **mandatory** for this run. Wherever a later step requires understanding code, mapping relationships across files, or making a design decision, you MUST first run Graphify on the relevant input (the affected file(s), the PR/MR diff, or the surrounding module) and use the resulting knowledge graph to inform your work. This applies in particular to: + +- **Step 4** — understanding each comment in the context of the surrounding code. +- **Step 4b** — every deferred item: build the graph for the item's scope before choosing and executing a design route. +- **Step 6** — self-review: graph the diff to check cross-file impact. + +If Graphify is **not** available, proceed normally — do not block on it. + +Record availability as a transient session fact — do NOT persist it; skill availability can change between sessions. + ## Step 1: Platform Detection & CLI Verification ### 1.1 Check Memory @@ -190,7 +206,7 @@ When a comment is unclear, ask **one** short clarifying question. Before asking, Then work through each task sequentially: 1. **Read the affected file** at the referenced location -2. **Understand the comment** in the context of the surrounding code +2. **Understand the comment** in the context of the surrounding code (if Graphify is available per Step 0, graph the affected file(s) first and use the result to understand the surrounding code) 3. If the comment is marked `(outdated)`, check whether the feedback is still relevant before acting 4. **If unclear**: Ask the user what exactly is expected. Ask the user directly in chat with the listed options. 5. **Implement the change** according to the reviewer's feedback @@ -209,6 +225,8 @@ Otherwise announce: "Now handling N deferred items." Process items strictly in t For each deferred item: +0. If Graphify is available (Step 0), build the knowledge graph for this item's scope first and use it to inform the route choice and execution below. + 1. Detect which design skills are visible to the running agent: These harnesses do not currently expose a skills registry; assume `[s]` and `[b]` are unavailable. Show them marked unavailable; allow the user to type a path to a local skill file if they want to invoke one manually. Record this as a transient session fact — do NOT persist it. @@ -262,6 +280,8 @@ Review all changes made: git diff ``` +If Graphify is available (Step 0), graph the diff and use the result to check cross-file impact and relationships before the checks below. + Check for: ### Reusability diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..21780e6 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,128 @@ +# Architecture + +This repository is a **multi-agent skill plugin**. A single source is compiled into +per-agent variants for Claude Code, Codex, Augment, Junie, and Roo Code. You never +edit the compiled output by hand — you edit the sources and run the build. + +## The core idea: one source, many targets + +``` +core/ + adapters// scripts/build.sh generated, committed +───────────────────────── ──────────────────────────▶ ───────────────────────── +core/kernel.md skills/ (claude) +core/platforms/*.md dist//... (codex, augment, junie, roo) +adapters//frontmatter.yaml plugins//... (marketplace bundles) +adapters//prelude.md +adapters//snippets/*.md +``` + +## Source files (edit these) + +| Path | Purpose | +|------|---------| +| `core/kernel.md` | The shared skill body for **all** agents. Contains `` placeholders. | +| `core/platforms/*.md` | Per-platform modules (`github`, `gitlab`, `bitbucket`, `azure`). Also contain adapter placeholders. | +| `adapters//frontmatter.yaml` | The YAML frontmatter for that agent's `SKILL.md`. | +| `adapters//prelude.md` | Agent-specific intro prepended before the kernel. | +| `adapters//snippets/.md` | Replacement text for each `` placeholder. A missing snippet substitutes to empty (the agent omits that step). | +| `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, `.augment-plugin/plugin.json` | Manifest **sources**. | +| `.claude-plugin/marketplace.json`, `.augment-plugin/marketplace.json`, `.agents/plugins/marketplace.json` | Marketplace definitions. | +| `scripts/`, `tests/` | Build / install / validate / smoke-test. | + +## Generated artifacts (never edit — `build.sh` overwrites them) + +| Path | What | Used by | +|------|------|---------| +| `skills/resolve-comments/` | Claude's built skill | Claude discovers skills under `skills/` at the repo root, so Claude's output lives here instead of under `dist/`. | +| `dist//...` | Built skills for the **other four** agents | `scripts/install.sh` (codex, roo, junie copy from here) and as the source for bundling (codex, augment). | +| `plugins//pr-comments-resolver/` | Ready-to-distribute marketplace bundles | The three marketplace agents: **claude, codex, augment**. Each bundle = manifest dir + `icon.png` + `skills/`. The `marketplace.json` files point here. | + +**Junie and Roo deliberately have no `plugins/` bundle and no `plugin.json`** — they have +no marketplace format and are installed only via `scripts/install.sh`. + +## How the build works (`scripts/build.sh`) + +For each agent: + +1. Concatenate `---` + `adapters//frontmatter.yaml` + `---` + `adapters//prelude.md` + the substituted kernel. +2. `scripts/substitute.py` replaces every `` in `core/kernel.md` (and each `core/platforms/*.md`) with the matching `adapters//snippets/.md`. +3. Write the result to the agent's output path (`skills/` for claude, `dist//...` for the rest), plus a sibling `platforms/` directory. +4. `package_marketplace_plugin` copies the built skill tree + manifest + icon into `plugins//pr-comments-resolver/` (claude, codex, augment only). + +```bash +bash scripts/build.sh all # build every agent +bash scripts/build.sh claude # build a single agent +``` + +## Per-agent `plugin.json` + +The distinguishing field is `skills`: + +| Agent | `skills` field | Notes | +|-------|----------------|-------| +| **Claude** | *(none)* | Claude auto-discovers `skills/`. Manifest has `name`, `version`, `description`, `author`, `homepage`, `license`, `icon`, `keywords`. | +| **Codex** | `"./dist/codex/skills/"` in source → rewritten to `"./skills/"` when bundled into `plugins/codex/` | Additionally carries a Codex-specific `interface` block (`displayName`, `shortDescription`, `defaultPrompt`, `brandColor`, `composerIcon`, …). | +| **Augment** | `"./dist/augment/skills/"` in source → rewritten to `"./skills/"` when bundled | Minimal manifest: `name`, `version`, `description`, `author`, `keywords`. | + +The `skills`-path rewrite happens in `build.sh` (`package_marketplace_plugin`) because the +bundle ships the skills relatively under its own `skills/` directory. + +## Graphify integration + +The kernel opens with **Step 0: Graphify Availability**. If a `graphify` skill is available +in the running agent, the skill is *required* to use it wherever it needs to understand code, +map cross-file relationships, or make a design decision — specifically Step 4 (comment context), +Step 4b (deferred items), and Step 6 (self-review). If Graphify is absent, the flow proceeds +normally. + +Detection is adapter-specific via the `` placeholder +(`adapters//snippets/graphify-availability.md`): the Claude adapter checks the harness +skills registry, while the others — which expose no registry — treat Graphify as available only +when the project demonstrably ships it. Availability is a transient session fact and is never +persisted. + +## Validation (`scripts/validate.py`) + +Checks every generated `SKILL.md`: required frontmatter keys (`name`, `description`), +the `description` starts with `Use when` and is ≤ 500 chars, no stray `` +placeholders remain, all four platform modules exist per agent, and the three plugin +bundles are present and complete. + +## CI/CD flow + +Two workflows, distinct roles: + +### `verify-build.yml` — on every pull request + +Builds all agents, validates, runs the smoke test. It does **not** require contributors +to commit generated artifacts (`skills/`, `dist/`, `plugins/`) — those are produced +automatically after merge. + +### `release.yml` — on push to `main` + +A single ordered pipeline: + +1. Determine the next SemVer version (dry-run, no tag yet). +2. Sync that version into all manifests (`.claude-plugin/`, `.codex-plugin/`, `.augment-plugin/`). +3. `bash scripts/build.sh all` — regenerate `skills/`, `dist/`, `plugins/`. +4. Validate + smoke-test. +5. Commit the regenerated artifacts + manifests back to `main` (only if changed), with `[skip ci]`. +6. Create and push the version tag **on that artifact commit** (not on the triggering merge commit). + +The tag therefore always points at a commit that already contains the freshly generated +artifacts. When Claude or Codex download the repo at a tag, `skills/`, `dist/`, `plugins/` +and the versioned manifests are all present. + +**Loop prevention:** commits pushed with the default `GITHUB_TOKEN` do not trigger new +workflow runs; `[skip ci]` is a second safeguard; tag pushes don't trigger the workflow. + +**Branch-protection requirement:** `github-actions[bot]` (via `GITHUB_TOKEN` with +`contents: write`) must be allowed to push directly to `main`. If `main` requires pull +requests, the bot must be on the bypass list — otherwise step 5 fails. + +## Working on the project + +1. Edit `core/` (content) and/or `adapters//` (per-agent), or a `.X-plugin/plugin.json` (manifest). +2. Run `bash scripts/build.sh all`. +3. Run `python3 scripts/validate.py` and `bash tests/build_test.sh`. +4. Never hand-edit `skills/`, `dist/`, or `plugins/` — they are regenerated. diff --git a/plugins/augment/pr-comments-resolver/skills/resolve-comments/SKILL.md b/plugins/augment/pr-comments-resolver/skills/resolve-comments/SKILL.md index 13d5280..6cea10a 100644 --- a/plugins/augment/pr-comments-resolver/skills/resolve-comments/SKILL.md +++ b/plugins/augment/pr-comments-resolver/skills/resolve-comments/SKILL.md @@ -9,6 +9,22 @@ Work through all unresolved review comments from a pull request or merge request > This skill activates implicitly when its description matches your request. You can also reference it explicitly by name. +## Step 0: Graphify Availability (mandatory if present) + +Before anything else, check whether the **Graphify** skill is available in the running agent for this project. + +These harnesses do not expose a skills registry. Treat Graphify as available only if the project clearly ships it (e.g. a `graphify` skill/command file under the project's skills directory or an entry in the agent config). If you cannot positively confirm it, treat Graphify as unavailable and proceed without it. + +If Graphify **is** available, using it is **mandatory** for this run. Wherever a later step requires understanding code, mapping relationships across files, or making a design decision, you MUST first run Graphify on the relevant input (the affected file(s), the PR/MR diff, or the surrounding module) and use the resulting knowledge graph to inform your work. This applies in particular to: + +- **Step 4** — understanding each comment in the context of the surrounding code. +- **Step 4b** — every deferred item: build the graph for the item's scope before choosing and executing a design route. +- **Step 6** — self-review: graph the diff to check cross-file impact. + +If Graphify is **not** available, proceed normally — do not block on it. + +Record availability as a transient session fact — do NOT persist it; skill availability can change between sessions. + ## Step 1: Platform Detection & CLI Verification ### 1.1 Check Memory @@ -190,7 +206,7 @@ When a comment is unclear, ask **one** short clarifying question. Before asking, Then work through each task sequentially: 1. **Read the affected file** at the referenced location -2. **Understand the comment** in the context of the surrounding code +2. **Understand the comment** in the context of the surrounding code (if Graphify is available per Step 0, graph the affected file(s) first and use the result to understand the surrounding code) 3. If the comment is marked `(outdated)`, check whether the feedback is still relevant before acting 4. **If unclear**: Ask the user what exactly is expected. Ask the user directly in chat with the listed options. 5. **Implement the change** according to the reviewer's feedback @@ -209,6 +225,8 @@ Otherwise announce: "Now handling N deferred items." Process items strictly in t For each deferred item: +0. If Graphify is available (Step 0), build the knowledge graph for this item's scope first and use it to inform the route choice and execution below. + 1. Detect which design skills are visible to the running agent: These harnesses do not currently expose a skills registry; assume `[s]` and `[b]` are unavailable. Show them marked unavailable; allow the user to type a path to a local skill file if they want to invoke one manually. Record this as a transient session fact — do NOT persist it. @@ -262,6 +280,8 @@ Review all changes made: git diff ``` +If Graphify is available (Step 0), graph the diff and use the result to check cross-file impact and relationships before the checks below. + Check for: ### Reusability diff --git a/plugins/claude/pr-comments-resolver/skills/resolve-comments/SKILL.md b/plugins/claude/pr-comments-resolver/skills/resolve-comments/SKILL.md index ca31316..ef30d21 100644 --- a/plugins/claude/pr-comments-resolver/skills/resolve-comments/SKILL.md +++ b/plugins/claude/pr-comments-resolver/skills/resolve-comments/SKILL.md @@ -8,6 +8,22 @@ trigger: /resolve-comments Work through all unresolved review comments from a pull request or merge request on GitHub, GitLab, Bitbucket Cloud, or Azure DevOps. +## Step 0: Graphify Availability (mandatory if present) + +Before anything else, check whether the **Graphify** skill is available in the running agent for this project. + +Check the list of available skills surfaced by the harness for a `graphify` skill (it may appear as `graphify` or a plugin-namespaced `:graphify`). If present, Graphify is available; invoke it via the Skill tool when required below. + +If Graphify **is** available, using it is **mandatory** for this run. Wherever a later step requires understanding code, mapping relationships across files, or making a design decision, you MUST first run Graphify on the relevant input (the affected file(s), the PR/MR diff, or the surrounding module) and use the resulting knowledge graph to inform your work. This applies in particular to: + +- **Step 4** — understanding each comment in the context of the surrounding code. +- **Step 4b** — every deferred item: build the graph for the item's scope before choosing and executing a design route. +- **Step 6** — self-review: graph the diff to check cross-file impact. + +If Graphify is **not** available, proceed normally — do not block on it. + +Record availability as a transient session fact — do NOT persist it; skill availability can change between sessions. + ## Step 1: Platform Detection & CLI Verification ### 1.1 Check Memory @@ -215,7 +231,7 @@ When a comment is unclear, ask **one** short clarifying question. Before asking, Then work through each task sequentially: 1. **Read the affected file** at the referenced location -2. **Understand the comment** in the context of the surrounding code +2. **Understand the comment** in the context of the surrounding code (if Graphify is available per Step 0, graph the affected file(s) first and use the result to understand the surrounding code) 3. If the comment is marked `(outdated)`, check whether the feedback is still relevant before acting 4. **If unclear**: Ask the user what exactly is expected. Use AskUserQuestion to present the options. 5. **Implement the change** according to the reviewer's feedback @@ -234,6 +250,8 @@ Otherwise announce: "Now handling N deferred items." Process items strictly in t For each deferred item: +0. If Graphify is available (Step 0), build the knowledge graph for this item's scope first and use it to inform the route choice and execution below. + 1. Detect which design skills are visible to the running agent: Check the list of available skills surfaced by the harness. Note whether `superpowers:brainstorming` and either `sdd` or `superpowers:sdd` are present. Record this as a transient session fact — do NOT persist it; skill availability can change between sessions. @@ -289,6 +307,8 @@ Review all changes made: git diff ``` +If Graphify is available (Step 0), graph the diff and use the result to check cross-file impact and relationships before the checks below. + Check for: ### Reusability diff --git a/plugins/codex/pr-comments-resolver/skills/resolve-comments/SKILL.md b/plugins/codex/pr-comments-resolver/skills/resolve-comments/SKILL.md index 7e32016..e7a6afc 100644 --- a/plugins/codex/pr-comments-resolver/skills/resolve-comments/SKILL.md +++ b/plugins/codex/pr-comments-resolver/skills/resolve-comments/SKILL.md @@ -9,6 +9,22 @@ Work through all unresolved review comments from a pull request or merge request > Invoke this skill via `$resolve-comments` or the `/skills` command. This skill is stateless: platform detection runs on every invocation. +## Step 0: Graphify Availability (mandatory if present) + +Before anything else, check whether the **Graphify** skill is available in the running agent for this project. + +These harnesses do not expose a skills registry. Treat Graphify as available only if the project clearly ships it (e.g. a `graphify` skill/command file under the project's skills directory or an entry in the agent config). If you cannot positively confirm it, treat Graphify as unavailable and proceed without it. + +If Graphify **is** available, using it is **mandatory** for this run. Wherever a later step requires understanding code, mapping relationships across files, or making a design decision, you MUST first run Graphify on the relevant input (the affected file(s), the PR/MR diff, or the surrounding module) and use the resulting knowledge graph to inform your work. This applies in particular to: + +- **Step 4** — understanding each comment in the context of the surrounding code. +- **Step 4b** — every deferred item: build the graph for the item's scope before choosing and executing a design route. +- **Step 6** — self-review: graph the diff to check cross-file impact. + +If Graphify is **not** available, proceed normally — do not block on it. + +Record availability as a transient session fact — do NOT persist it; skill availability can change between sessions. + ## Step 1: Platform Detection & CLI Verification ### 1.1 Check Memory @@ -175,7 +191,7 @@ When a comment is unclear, ask **one** short clarifying question. Before asking, Then work through each task sequentially: 1. **Read the affected file** at the referenced location -2. **Understand the comment** in the context of the surrounding code +2. **Understand the comment** in the context of the surrounding code (if Graphify is available per Step 0, graph the affected file(s) first and use the result to understand the surrounding code) 3. If the comment is marked `(outdated)`, check whether the feedback is still relevant before acting 4. **If unclear**: Ask the user what exactly is expected. Ask the user directly in chat with the listed options. 5. **Implement the change** according to the reviewer's feedback @@ -194,6 +210,8 @@ Otherwise announce: "Now handling N deferred items." Process items strictly in t For each deferred item: +0. If Graphify is available (Step 0), build the knowledge graph for this item's scope first and use it to inform the route choice and execution below. + 1. Detect which design skills are visible to the running agent: These harnesses do not currently expose a skills registry; assume `[s]` and `[b]` are unavailable. Show them marked unavailable; allow the user to type a path to a local skill file if they want to invoke one manually. Record this as a transient session fact — do NOT persist it. @@ -247,6 +265,8 @@ Review all changes made: git diff ``` +If Graphify is available (Step 0), graph the diff and use the result to check cross-file impact and relationships before the checks below. + Check for: ### Reusability diff --git a/skills/resolve-comments/SKILL.md b/skills/resolve-comments/SKILL.md index ca31316..ef30d21 100644 --- a/skills/resolve-comments/SKILL.md +++ b/skills/resolve-comments/SKILL.md @@ -8,6 +8,22 @@ trigger: /resolve-comments Work through all unresolved review comments from a pull request or merge request on GitHub, GitLab, Bitbucket Cloud, or Azure DevOps. +## Step 0: Graphify Availability (mandatory if present) + +Before anything else, check whether the **Graphify** skill is available in the running agent for this project. + +Check the list of available skills surfaced by the harness for a `graphify` skill (it may appear as `graphify` or a plugin-namespaced `:graphify`). If present, Graphify is available; invoke it via the Skill tool when required below. + +If Graphify **is** available, using it is **mandatory** for this run. Wherever a later step requires understanding code, mapping relationships across files, or making a design decision, you MUST first run Graphify on the relevant input (the affected file(s), the PR/MR diff, or the surrounding module) and use the resulting knowledge graph to inform your work. This applies in particular to: + +- **Step 4** — understanding each comment in the context of the surrounding code. +- **Step 4b** — every deferred item: build the graph for the item's scope before choosing and executing a design route. +- **Step 6** — self-review: graph the diff to check cross-file impact. + +If Graphify is **not** available, proceed normally — do not block on it. + +Record availability as a transient session fact — do NOT persist it; skill availability can change between sessions. + ## Step 1: Platform Detection & CLI Verification ### 1.1 Check Memory @@ -215,7 +231,7 @@ When a comment is unclear, ask **one** short clarifying question. Before asking, Then work through each task sequentially: 1. **Read the affected file** at the referenced location -2. **Understand the comment** in the context of the surrounding code +2. **Understand the comment** in the context of the surrounding code (if Graphify is available per Step 0, graph the affected file(s) first and use the result to understand the surrounding code) 3. If the comment is marked `(outdated)`, check whether the feedback is still relevant before acting 4. **If unclear**: Ask the user what exactly is expected. Use AskUserQuestion to present the options. 5. **Implement the change** according to the reviewer's feedback @@ -234,6 +250,8 @@ Otherwise announce: "Now handling N deferred items." Process items strictly in t For each deferred item: +0. If Graphify is available (Step 0), build the knowledge graph for this item's scope first and use it to inform the route choice and execution below. + 1. Detect which design skills are visible to the running agent: Check the list of available skills surfaced by the harness. Note whether `superpowers:brainstorming` and either `sdd` or `superpowers:sdd` are present. Record this as a transient session fact — do NOT persist it; skill availability can change between sessions. @@ -289,6 +307,8 @@ Review all changes made: git diff ``` +If Graphify is available (Step 0), graph the diff and use the result to check cross-file impact and relationships before the checks below. + Check for: ### Reusability diff --git a/tests/build_test.sh b/tests/build_test.sh index e2736b1..e353b4f 100755 --- a/tests/build_test.sh +++ b/tests/build_test.sh @@ -14,7 +14,7 @@ grep -q 'TodoWrite' "$OUT" || { echo "FAIL: track-tasks snippet not substituted" grep -q 'CLAUDE.md' "$OUT" || { echo "FAIL: context-file-name snippet not substituted"; exit 1; } ! grep -q '