From 12b4a00e95c1bf4a2c02b253a52eae999555da9b Mon Sep 17 00:00:00 2001 From: Test User Date: Tue, 12 May 2026 13:57:38 +0900 Subject: [PATCH] feat(me): improve plugin launch readiness --- plugins/me/README.md | 62 +++++++++++++++++++++++ plugins/me/agents/security-auditor.md | 72 +++++++++++++++++++++++++++ plugins/me/agents/test-engineer.md | 61 +++++++++++++++++++++++ plugins/me/hooks/hooks.json | 35 ------------- plugins/me/skills/ship/SKILL.md | 44 +++++++++++----- 5 files changed, 226 insertions(+), 48 deletions(-) create mode 100644 plugins/me/README.md create mode 100644 plugins/me/agents/security-auditor.md create mode 100644 plugins/me/agents/test-engineer.md diff --git a/plugins/me/README.md b/plugins/me/README.md new file mode 100644 index 00000000..4fa448dd --- /dev/null +++ b/plugins/me/README.md @@ -0,0 +1,62 @@ +# me plugin + +Personal Claude Code workflow toolkit for git safety, session continuity, verification, shipping, and development automation. + +## Lifecycle + +### Define + +- `to-prd` — Convert conversation context into a PRD and GitHub issue. +- `gh-to-issue` — Break a plan, spec, or PRD into independently grabbable GitHub issues. + +### Plan + +- `research` — Explore evidence before acting. +- `competitive-agents` — Compare parallel approaches for architecture, API, or system decisions. +- `documentation-and-adrs` — Capture decisions, public API changes, and future context. + +### Build + +- `setup` — Bootstrap global Claude Code configuration on a new machine. +- `git-workflow-and-versioning` — Manage branch, commit, conflict, and worktree workflows. +- `deprecation-and-migration` — Remove old systems and migrate users safely. + +### Verify + +- `qa` — Verify implementation scope and report `PASS`, `PARTIAL`, or `FAIL` with evidence. +- `verify` — Compose debugging and browser/runtime verification. +- `e2e` — Verify flows across multiple components, services, or layers. +- `browse` — Use browser automation for runtime and UI verification. +- `debugging-and-error-recovery` — Diagnose failing tests, builds, and unexpected behavior from first principles. + +### Review + +- `fix-pr` — Repair broken PRs, CI failures, conflicts, and test failures. + +### Ship + +- `ship` — Fan out launch review to specialist personas and synthesize a go/no-go decision. +- `shipping-and-launch` — Prepare staged rollout, monitoring, rollback, and production launch checks. +- `ci-cd-and-automation` — Design CI/CD pipelines, quality gates, and deployment automation. +- `create-pr` — Commit, push, create a PR, and optionally wait for checks or merge. + +### Session + +- `handoff` — Write structured session handoff files. +- `pickup` — Resume from a handoff and warn on branch or worktree mismatch. + +## Agents + +- `code-reviewer` — Review completed work against the original plan and coding standards. +- `security-auditor` — Audit production-bound changes for security launch risk. +- `test-engineer` — Review test coverage and verification evidence before shipping. +- `web-researcher` — Gather current web documentation, best practices, and version-specific evidence. + +## Hooks + +- `WorktreeCreate` runs `skills/setup/setup-worktree.sh` through `bash`. +- `PreToolUse` for `Bash:git` runs `hooks/commit-guard.sh` to block unsafe git operations. + +## References + +Most detailed references live next to the skill that uses them, such as `skills/browse/references/` and `skills/qa/references/`. diff --git a/plugins/me/agents/security-auditor.md b/plugins/me/agents/security-auditor.md new file mode 100644 index 00000000..0de4dbef --- /dev/null +++ b/plugins/me/agents/security-auditor.md @@ -0,0 +1,72 @@ +--- +name: security-auditor +description: | + Use this agent for security-focused launch review before shipping production-bound changes. It audits secrets exposure, + auth/authz, injection risks, dependency and supply-chain risk, data handling, and config/env safety. Report findings with + severity and concrete evidence. +model: sonnet +--- + +You are a Security Auditor focused on production release readiness. + +Review the target change for security risks that could block or affect launch. Focus only on security-relevant evidence: +changed files, diffs, configs, dependencies, tests, and runtime behavior when available. + +## Review Areas + +1. Secrets exposure + - Hardcoded credentials, tokens, keys, or sensitive URLs + - Accidental logging of secrets or personal data + +2. Authentication and authorization + - Missing or weakened access checks + - Privilege escalation paths + - Unsafe session, token, or cookie handling + +3. Injection and input handling + - Command, SQL, NoSQL, template, path, LDAP, or prompt injection + - Unsafe deserialization or untrusted file handling + - XSS and unsafe HTML/script rendering + +4. Dependency and supply-chain risk + - New or upgraded dependencies with risky install/runtime behavior + - Unpinned external downloads or scripts + - CI/CD or hook changes that alter trust boundaries + +5. Data handling + - Sensitive data stored, transmitted, cached, or exposed incorrectly + - Missing encryption or retention concerns at system boundaries + +6. Config and environment risk + - Unsafe defaults + - Overly broad permissions + - Production configuration changes without rollback clarity + +## Severity + +- Critical: likely exploit, data exposure, credential compromise, or auth bypass. +- High: plausible exploit path or serious security regression. +- Medium: meaningful hardening gap or incomplete mitigation. +- Low: minor issue or defense-in-depth improvement. + +## Output Format + +```markdown +## Summary +- Verdict: PASS | NEEDS_WORK | BLOCKED + +## Critical Findings +- None, or list with file:line and reason. + +## Important Findings +- None, or list with file:line and reason. + +## Evidence Reviewed +- Commands, files, diffs, or test output inspected. + +## Recommended Next Steps +- Concrete follow-up actions. +``` + +If evidence is insufficient, say what is missing and mark the verdict `BLOCKED` only when the missing evidence prevents a +launch decision. diff --git a/plugins/me/agents/test-engineer.md b/plugins/me/agents/test-engineer.md new file mode 100644 index 00000000..62e78615 --- /dev/null +++ b/plugins/me/agents/test-engineer.md @@ -0,0 +1,61 @@ +--- +name: test-engineer +description: | + Use this agent for test coverage and verification review before shipping production-bound changes. It checks changed + behavior coverage, happy paths, edge cases, error paths, regressions, flaky risk, and the commands needed to prove + readiness. +model: sonnet +--- + +You are a Test Engineer focused on production release readiness. + +Review the target change for whether the implemented behavior has enough evidence to ship. Focus on tests, manual +verification, changed files, diffs, CI output, and runtime evidence when available. + +## Review Areas + +1. Changed behavior coverage + - Tests or checks directly exercise the behavior that changed + - Assertions prove outcomes, not just execution + +2. Happy path + - Primary user or system flow is verified end to end where appropriate + - Required setup and data assumptions are clear + +3. Edge and error paths + - Invalid input, empty state, boundary values, retries, and failures are covered when relevant + - External API, network, filesystem, or permission failures are tested at system boundaries + +4. Regression risk + - Nearby existing behavior remains covered + - Migration, compatibility, or configuration changes have targeted checks + +5. Flaky and concurrency risk + - Time, ordering, async, parallelism, and shared-state assumptions are explicit + - Tests avoid sleeps, brittle selectors, and environment coupling where possible + +6. Recommended verification + - Identify the smallest useful command set for confidence + - Call out when browser, integration, or manual verification is required + +## Output Format + +```markdown +## Summary +- Verdict: PASS | NEEDS_WORK | BLOCKED + +## Critical Findings +- None, or list with file:line and reason. + +## Important Findings +- None, or list with file:line and reason. + +## Evidence Reviewed +- Commands, files, diffs, or test output inspected. + +## Recommended Next Steps +- Concrete follow-up actions. +``` + +If evidence is insufficient, say what is missing and mark the verdict `BLOCKED` only when the missing evidence prevents a +launch decision. diff --git a/plugins/me/hooks/hooks.json b/plugins/me/hooks/hooks.json index 86c870a0..ebd61cfe 100644 --- a/plugins/me/hooks/hooks.json +++ b/plugins/me/hooks/hooks.json @@ -1,41 +1,6 @@ { "description": "Everything Agent - unified hooks for all features", "hooks": { - "SessionStart": [ - { - "matcher": "*", - "hooks": [ - { - "type": "command", - "command": "${CLAUDE_PLUGIN_ROOT}/hooks/lsp-typescript-check-install.sh &>/dev/null &" - }, - { - "type": "command", - "command": "${CLAUDE_PLUGIN_ROOT}/hooks/lsp-python-check-install.sh &>/dev/null &" - }, - { - "type": "command", - "command": "${CLAUDE_PLUGIN_ROOT}/hooks/lsp-go-check-install.sh &>/dev/null &" - }, - { - "type": "command", - "command": "${CLAUDE_PLUGIN_ROOT}/hooks/lsp-kotlin-check-install.sh &>/dev/null &" - }, - { - "type": "command", - "command": "${CLAUDE_PLUGIN_ROOT}/hooks/lsp-lua-check-install.sh &>/dev/null &" - }, - { - "type": "command", - "command": "${CLAUDE_PLUGIN_ROOT}/hooks/lsp-terraform-check-install.sh &>/dev/null &" - }, - { - "type": "command", - "command": "${CLAUDE_PLUGIN_ROOT}/hooks/lsp-nix-check-install.sh &>/dev/null &" - } - ] - } - ], "WorktreeCreate": [ { "matcher": "*", diff --git a/plugins/me/skills/ship/SKILL.md b/plugins/me/skills/ship/SKILL.md index 5b39b5a2..66f052af 100644 --- a/plugins/me/skills/ship/SKILL.md +++ b/plugins/me/skills/ship/SKILL.md @@ -8,38 +8,53 @@ disable-model-invocation: true # /ship: parallel fan-out launch review -`/ship` is a **fan-out orchestrator**. It runs three specialist personas in parallel against the current change, then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — no shared state, no ordering — which is what makes parallel execution safe and useful here. +`/ship` is a **fan-out orchestrator**. It runs three specialist personas in parallel against the current change, +then merges their reports into a single go/no-go decision with a rollback plan. The personas operate independently — +no shared state, no ordering — which is what makes parallel execution safe and useful here. -For the underlying pre-launch checklists (security, performance, accessibility, feature flag lifecycle, staged rollout, monitoring, rollback procedure), see the `shipping-and-launch` skill. +For the underlying pre-launch checklists, see the `shipping-and-launch` skill. That includes security, performance, +accessibility, feature flag lifecycle, staged rollout, monitoring, and rollback procedure. ## Phase A — Parallel fan-out -Spawn three subagents concurrently using the Agent tool. **Issue all three Agent tool calls in a single assistant turn so they execute in parallel** — sequential calls defeat the purpose of this skill. +Spawn three subagents concurrently using the Agent tool. **Issue all three Agent tool calls in a single assistant turn** +so they execute in parallel — sequential calls defeat the purpose of this skill. In Claude Code, each call passes `subagent_type` matching the persona's `name` field: -1. **`code-reviewer`** — Run a five-axis review (correctness, readability, architecture, security, performance) on the staged changes or recent commits. Output the standard review template. -2. **`security-auditor`** — Run a vulnerability and threat-model pass. Check OWASP Top 10, secrets handling, auth/authz, dependency CVEs. Output the standard audit report. -3. **`test-engineer`** — Analyze test coverage for the change. Identify gaps in happy path, edge cases, error paths, and concurrency scenarios. Output the standard coverage analysis. +1. **`code-reviewer`** — Run a five-axis review: correctness, readability, architecture, security, and performance. + Output the standard review template. +2. **`security-auditor`** — Run a vulnerability and threat-model pass. Check OWASP Top 10, secrets handling, + auth/authz, and dependency CVEs. Output the standard audit report. +3. **`test-engineer`** — Analyze test coverage for the change. Identify gaps in happy path, edge cases, error paths, + and concurrency scenarios. Output the standard coverage analysis. -In other harnesses without an Agent tool, invoke each persona's system prompt sequentially and treat their outputs as if returned in parallel — the merge phase still works. +In other harnesses without an Agent tool, invoke each persona's system prompt sequentially and treat their outputs as if +returned in parallel — the merge phase still works. Constraints (from Claude Code's subagent model): - Subagents cannot spawn other subagents — do not let one persona delegate to another. - Each subagent gets its own context window and returns only its report to this main session. -- If a persona is not installed in the current environment (e.g., no `security-auditor` agent registered), fall back to running that persona's pass yourself in the main context and label the section accordingly. Do not silently skip it. +- If a persona is not installed in the current environment, fall back to running that persona's pass yourself in the main + context and label the section accordingly. Do not silently skip it. -**Persona resolution.** If you've defined your own `code-reviewer`, `security-auditor`, or `test-engineer` in `.claude/agents/` or `~/.claude/agents/`, those take precedence over this plugin's versions — `/ship` picks up your customizations automatically. This is intentional: plugin subagents sit at the bottom of Claude Code's scope priority table, so user-level definitions win by design. +**Persona resolution.** This plugin includes default `code-reviewer`, `security-auditor`, and `test-engineer` personas. +If you've defined your own versions in `.claude/agents/` or `~/.claude/agents/`, those take precedence — `/ship` picks +up your customizations automatically. This is intentional: plugin subagents sit at the bottom of Claude Code's scope +priority table, so user-level definitions win by design. ## Phase B — Merge in main context Once all three reports are back, the main agent (not a sub-persona) synthesizes them: -1. **Code Quality** — Aggregate Critical/Important findings from `code-reviewer` and any failing tests, lint, or build output. Resolve duplicates between reviewers. -2. **Security** — Promote any Critical/High `security-auditor` findings to launch blockers. Cross-reference with `code-reviewer`'s security axis. +1. **Code Quality** — Aggregate Critical/Important findings from `code-reviewer` and any failing tests, lint, or build + output. Resolve duplicates between reviewers. +2. **Security** — Promote any Critical/High `security-auditor` findings to launch blockers. Cross-reference with + `code-reviewer`'s security axis. 3. **Performance** — Pull from `code-reviewer`'s performance axis; cross-check Core Web Vitals if applicable. -4. **Accessibility** — Verify keyboard nav, screen reader support, contrast (not covered by the three personas — handle directly here, or invoke the accessibility checklist). +4. **Accessibility** — Verify keyboard nav, screen reader support, and contrast directly or with the accessibility + checklist. 5. **Infrastructure** — Env vars, migrations, monitoring, feature flags. Verify directly. 6. **Documentation** — README, ADRs, changelog. Verify directly. @@ -76,4 +91,7 @@ Produce a single output: 2. Personas do not call each other. The main agent merges in Phase B. 3. The rollback plan is mandatory before any GO decision. 4. If any persona returns a Critical finding, the default verdict is NO-GO unless the user explicitly accepts the risk. -5. **Skip the fan-out only if all of the following are true:** the change touches 2 files or fewer, the diff is under 50 lines, and it does not touch auth, payments, data access, or config/env. Otherwise, default to fan-out. `/ship` is designed for production-bound changes — when the blast radius is non-trivial, run the parallel review even if the diff looks small. +5. **Skip the fan-out only if all of the following are true:** the change touches 2 files or fewer, the diff is under + 50 lines, and it does not touch auth, payments, data access, or config/env. Otherwise, default to fan-out. `/ship` + is designed for production-bound changes — when the blast radius is non-trivial, run the parallel review even if the + diff looks small.