Skip to content

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

138 Commits

Folders and files

Repository files navigation

proxy

Personal Claude Code plugin. Turns a product spec into a shipped, tested feature — everything runs in this conversation, with you. pair has you approve twice, live — once on the build plan, once on the QA plan. solo runs the same loop for work of any size and makes the calls itself.

There is no background/headless mode. Earlier versions of this plugin used Claude Code Workflows to run implementation and QA headless in the background — that was dropped deliberately after real testing surfaced enough fragility (undefined args, wrong tool grants, wrong hooks schema, redundant review phases) that a simpler, fully live design won out. pair covers building; qa-plan covers testing; solo is autonomous but still runs in the same live session, same loop, and you can interrupt it to steer at any point.

Setup and prerequisites

In Claude Code, add the marketplace and install the plugin:

/plugin marketplace add FurlanLuka/claude-proxy-plugin
/plugin install proxy@proxy-marketplace

Verify that the proxy: skills and advisor agents appear in the session. For local development, start Claude Code with claude --plugin-dir /absolute/path/to/claude-proxy-plugin from the target project.

See Prerequisites for workflow requirements and Artifact skill setup for access to Claude Code's built-in authoring skills.

Walkthrough prerequisites apply when a walkthrough is needed. A required walkthrough with missing capabilities blocks at that step; it is not silently omitted. Ordinary brainstorming, advisory review, and QA do not require artifact publishing.

Advisor execution modes

The advisors are product, architecture, clean-code and testing, each named after the standards file it applies (<name>-principles.md). Each explicitly reads the shared advisor execution rules. pair implements their recommendations in the main session. Advisors may use Bash for inspection, but their instructions prohibit file edits, mutating commands, and implementation. This is a behavioral boundary: Bash remains available, so omitting Edit/Write alone does not enforce filesystem isolation.

An advisor launched as the interactive main session, for example claude --agent proxy:architecture, can ask the user questions through AskUserQuestion when available. A spawned advisor returns assumptions and unresolved decisions to its parent without asking the user. Reading an agent's Markdown as guidance in an existing session does not itself apply its frontmatter tool configuration.

Regression checks

Run the regression scenarios when changing workflow or agent instructions. Manifest validation checks packaging; it does not prove approval boundaries, reference loading, or advisor behavior.

How it works

 /proxy:brainstorm ──────────────────────────────────────────
      │   optional, and separate on purpose. You bring a
      │   half-formed idea, it reacts — opinion first, ~200
      │   words, no options menu, no plan, nothing written.
      │   Ends only when you say "plan this".
      ▼
you write a spec
      │
      ▼
 /proxy:pair ────────────────────────────────────────────────
      │   main session, interactive. Loads philosophy.md + product-
      │   principles.md always; architecture/clean-code/testing-
      │   principles.md for real specs.
      │   Checks for missing infra (tests/logs/deploy) and flags it
      │   early, as its own separate plan — never bolted onto the
      │   feature plan.
      │   Asks ONE question at a time, early, product + major-
      │   technical only — proposes a recommendation on technical
      │   calls rather than asking blind.
      │   Self-reviews the draft against product/architecture/
      │   clean-code/testing before you ever see it —
      │   loops fix → re-review → ask-if-needed until it holds up.
      │   Then plan-walkthrough: if the change is structural, draws
      │   the before/after architecture as an artifact page so you
      │   can see the shape instead of reading for it. Skips most
      │   plans on purpose.
      ▼
 real plan mode — you iterate live, same as normal Claude Code plan mode
      │   (walkthrough link sits at the top of the plan)
      │
      ▼
 approved → implements immediately, right here
      │
      │   Writes the code, tests, logs. Runs what it wrote, loops
      │   fix → retest until green. Stays unblocked through to the
      │   end — no questions mid-build unless something is a
      │   genuinely big blocker, not just a preference call.
      │   Then the post-build review (references/review-process.md):
      │   clean-code + testing + a correctness
      │   pass on every change, architecture + product on real
      │   features. Each finding is verified, blocking ones loop
      │   fix → re-review until the lens that raised them confirms.
      ▼
 done → proceeds straight into qa-plan, no need to ask for it
      ▼
 /proxy:qa-plan ─────────────────────────────────────────────
      │   main session, interactive. Researches what's actually
      │   available to test with FIRST (running instance? curl-able
      │   endpoints? browser tooling already set up?) — never plans
      │   around tooling that isn't there. Drafts concrete QA cases
      │   from the real diff.
      ▼
 real plan mode — same live iteration
      ▼
 approved → executes immediately, right here
      │
      │   Hits real endpoints, drives the UI if browser tooling
      │   exists, checks logs actually fire. Same "only use what's
      │   already there" constraint, same "stay unblocked" rule.
      ▼
 Report: exercised / passed / failed / couldn't verify

/proxy:solo

Same pipeline as pair, minus every stop. No clarification questions, no plan approval click, no QA approval click — the agent decides, logs each decision, and the final report leads with that list. Plan mode is still real (read-only exploration, plan file); the approval is answered by a plugin hook instead of you. Interrupt anytime to steer; it takes the redirect and keeps going.

This is not the same as pair with "you decide": that skips the questions but still stops for both approvals. solo stops for none, whatever the scope — new modules, schema migrations, infra gaps and product forks included. It makes those calls itself and flags the big ones at the top of the final report.

/proxy:review

Different shape entirely — audits an existing codebase against all references instead of building something new. No plan to approve; just scans and produces a findings report (product/architecture/clean-code/testing conformance). Report only, never fixes anything itself — that's a separate follow-up via pair if you want findings acted on.

/proxy:pr-review

Reviews someone else's GitHub PR against its actual target using proxy's advisors and a local correctness review, then presents verified findings and draft comments in chat. Preserves your checkout and uncommitted files; posting requires an explicit go-ahead (prerequisites).

/proxy:pr-open

Opens one PR per repo touched once the work is built, reviewed and QA'd. Follows the repo's own PR skill or template where there is one. Writes the description from the diff and checks every claim in it against the code, lists the stack or the sibling PRs in merge order, opens as a draft by default, and requests only the reviewers you named or the repo assigns. pair and solo invoke it when the request asked for a PR.

/proxy:pr-check

Your own open PRs. First a read-only status in merge order: CI, reviews, unresolved threads, conflicts, moved bases. Then it fixes what it can — verifies each review comment before acting on it, repairs CI, resolves conflicts and restacks — replies on the threads it fixed and re-requests review. Replies that push back are drafted for you, and it never merges unless you said to.

/proxy:typescript-style

How TypeScript and React get written, distilled from the Decentrl codebase: blank lines that separate decisions, names that say what they return (checkX, planX, xOf), terse comments that give the reason, params objects, pure rule modules beside thin services, returned error codes, prefixed log lines, and situation → outcome test names. It triggers on its own whenever code is written or reviewed in a TypeScript repo, and defers to a repo's existing formatter and conventions. References for React, tests, commits and one worked example sit under skills/typescript-style/references/. For TypeScript and React code, pair follows it while implementing, review audits against it, and the clean-code and test advisors shape their plans with it.

Directory layout

proxy/
├── .github/workflows/
│   └── release.yml        CI: validates both manifests, tests the hooks, then releases whenever plugin.json's version changes
├── .claude-plugin/
│   └── plugin.json        manifest — name/description/version/author, rest auto-discovered
├── skills/
│   ├── brainstorm/          bounce ideas, high level, no planning — react and push back, nothing written
│   ├── pair/                default build entry point — plan live, implement live, on approval
│   ├── solo/                pair with overrides — no questions, no approval clicks, decides everything itself
│   ├── review/              audits an existing codebase against all references — report only
│   ├── pr-review/           reviews another author's GitHub PR — draft locally, post on approval
│   ├── pr-open/             opens the PRs for finished work — description checked against the code, stack and rollout order linked
│   ├── pr-check/            your own open PRs — status, then review comments, CI, conflicts and restacking until mergeable
│   ├── typescript-style/    how TS and React get written: rhythm, naming, comments, errors, logs, tests
│   ├── qa-plan/             plan QA live, execute live, on approval
│   ├── plan-walkthrough/    visual before/after page for a plan, published before approval
│   └── context/             loads all references/ into the current chat on demand (manual)
├── hooks/
│   ├── hooks.json                 PreToolUse on Skill and AskUserQuestion, PermissionRequest on ExitPlanMode, UserPromptSubmit — see Hooks below
│   ├── arm-solo-marker.sh         creates the session marker when the model invokes proxy:solo via the Skill tool, removes it on proxy:pair or proxy:brainstorm
│   ├── approve-solo-plan.sh       approves ExitPlanMode only while the marker exists
│   ├── block-solo-question.sh     denies AskUserQuestion while the marker exists
│   ├── prompt-solo-marker.sh      a typed /proxy:solo arms the marker; a typed /proxy:pair, /proxy:brainstorm or "stop solo" removes it
│   └── solo-hooks.test.sh         black-box tests for the hooks and the wiring, run in CI
├── agents/
│   ├── product.md                scope/usefulness/positioning/UX — advisor, no Edit/Write
│   ├── architecture.md           system/module design — advisor, no Edit/Write
│   ├── clean-code.md             extraction/refactor plans; on a review, also leftovers and docs — advisor, no Edit/Write
│   └── testing.md                test strategy — advisor, no Edit/Write
├── references/
│   ├── advisor-execution.md        shared execution rules for advisor roles
│   ├── philosophy.md               universal — product taste, communication, delegation
│   ├── product-principles.md       prioritization, feature yes/no, positioning, UX
│   ├── architecture-principles.md  system design judgment (match-existing-conventions first), incl. integration across repos and clients
│   ├── clean-code-principles.md    extraction/refactor judgment, leftovers, docs that follow the change, comments
│   ├── testing-principles.md       test strategy judgment
│   ├── security-principles.md      auth, data, secrets, overrides, model input — applied by architecture when the work touches them
│   ├── review-process.md           how a review runs: lenses, brief, verification, the blocking-fix loop — shared by pair, solo and pr-review
│   ├── walkthrough-principles.md   what a change walkthrough says + its locked visual identity
│   └── data-analysis-principles.md population-level analysis, source cross-referencing, claim verification
  • All advisor agents produce findings/plans and leave implementation to the main session; see the execution boundaries above.
  • pair and solo write and test application code in the main session.
  • qa-plan exercises the implementation directly in the main session.
  • The walkthrough skills create and publish visual artifacts under their own prerequisite rules.
  • pr-review drafts PR reviews in the main session and posts only the approved draft; its advisors remain read-only.
  • pr-open and pr-check push to and comment on your own PRs when invoked; neither merges, approves or argues with a reviewer without your go-ahead.

Hooks

These are the first hooks since the original two were dropped, and they exist only so solo can pass through plan mode without a click and without asking questions. All of them are no-ops unless a solo run is active, so pair and everything else are unaffected. The switch is a per-session marker file, /tmp/claude-proxy-solo-<session_id>, and only hooks ever touch it — the model never does.

  • PreToolUse on Skill — the model invoking proxy:solo creates the marker; proxy:pair or proxy:brainstorm removes it, since both exist to talk with you. Typing /proxy:solo yourself never calls the Skill tool (the command expands straight into the prompt), so the prompt hook below covers that path. The marker is created by the harness, not by a model-issued write. That matters: the auto-mode classifier denies a model creating its own approval switch as self-modification, which is exactly what happened when this was first tried.
  • PermissionRequest on ExitPlanMode — the plan-approval dialog is this permission prompt. The hook answers "allow" only if the marker exists; otherwise it stays silent and the normal dialog appears. ExitPlanMode is a user-interaction tool, so Claude Code honors the allow only when it comes with updatedInput echoing the plan back; a bare allow is silently ignored (the older docs example is stale). Echoing the plan needs a real JSON parser, so the hook uses jq or python3, whichever is present.
  • PreToolUse on AskUserQuestion — denied while the marker exists, with a reason telling the model to make the call and log it. solo promises no questions; this holds the model to it.
  • UserPromptSubmit — a prompt that starts with /proxy:solo arms the marker. A typed /proxy:pair or /proxy:brainstorm, or a prompt that is only "stop solo" or "exit solo", disarms it. Every other prompt leaves it armed. Earlier versions disarmed on any prompt outside plan mode, which ended solo in the middle of a run: subagent reports and task notifications arrive as prompts too, and solo runs six advisor passes per build, so the QA plan nearly always landed on the dialog. Steering a run did the same.

Things to know:

  • A solo session stays solo. The marker outlives the run, so a later plan in the same session also passes without a click until you say "stop solo", invoke pair or brainstorm, or start a new session.
  • It fails safe. Hooks not yet loaded, a missing session_id, an unwritable /tmp, neither jq nor python3 installed — all mean the dialog shows and you click. Never the other way round.
  • Approval restores whatever permission mode was active before plan mode. solo removes only the two plan approvals; every Edit and Bash call still follows your session mode.
  • Subagents share the session id, so a subagent calling ExitPlanMode during the window would also be approved. None of this plugin's agents enter plan mode.
  • Hooks load at session start. After installing or updating the plugin, run /reload-plugins or restart for them to take effect.

Principles this plugin encodes

The shared references define the product, engineering, and collaboration instructions used by the skills and agents.

  • Product decisions outrank specs — docs update to match decisions, never the reverse.
  • Match existing project conventions before applying any default in these references — for code AND for UX/product patterns.
  • Cut anything that doesn't earn its place — except tests and logs, which are never ceremony to cut.
  • No useless comments — code should be self-describable; comments only for context code genuinely can't express.
  • Reviewers own rigor; you own product judgment. Every implementation gets reviewed before it's "done," but scope calls stay yours.
  • One PR per repo touched, whole feature in one go — infra work is its own separate plan, never bolted onto a feature plan.
  • Once implementation starts, stay unblocked through to the end — ask only for a genuinely big blocker, not a preference call.
  • Use real plan mode for the two execution approvals: once for build, once for QA. Clarify decisions before drafting; after each approval, proceed through execution and ask only for a genuine blocker. In solo, a hook answers both approvals and there is no clarification phase.

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages