multi-forge 0.2.0__py3-none-any.whl

forge/__init__.py

@@ -0,0 +1,3 @@
+"""Multi-Forge - Multi-runtime agent toolkit."""
+
+__version__ = "0.2.0"

forge/_extensions/skills/analyze/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: forge:analyze
+description: Deep single-model analysis of a topic, question, or architectural decision.
+disable-model-invocation: false
+argument-hint: '[topic: path or question or instruction] [--output path] [--models model]'
+context: fork
+effort: high
+allowed-tools: Bash, Read
+---
+
+# Deep Analysis
+
+Deep analysis of a topic, question, or architectural decision using a dedicated model worker.
+
+## Usage
+
+```
+/forge:analyze [topic] [--models model]
+```
+
+## Arguments
+
+| Argument   | Required | Description                                                                            |
+| ---------- | -------- | -------------------------------------------------------------------------------------- |
+| `topic`    | Optional | Question, file path, directory, or instruction on what to analyze (defaults to asking) |
+| `--models` | Optional | Comma-separated model list (default: claude-opus)                                      |
+| `--output` | Optional | Write result to file instead of conversation (e.g., `analysis.md`)                     |
+
+**Available models:** !`forge workflow list-models`
+
+Only use models with status **ready** in the table above. If the default set includes unavailable models, pass
+`--models <ready models>` explicitly. If the user explicitly requested an unavailable model, stop and tell them what
+proxy or credential is missing rather than silently substituting. If no models are ready, tell the user what's missing
+and stop.
+
+---
+
+## Execution
+
+### Step 1: Resolve Topic and Flags
+
+Parse `$ARGUMENTS` into a positional topic and optional flags. The topic is everything that is not a recognized flag
+(question, file path, directory, or free-form instruction). Strip any leading `@` prefix on the topic. If no topic is
+found, ask the user what they want to analyze.
+
+Recognized flags (extract from `$ARGUMENTS` if present):
+
+- `--models <value>` — comma-separated model list (default: claude-opus)
+- `--output <path>` — write result to file instead of conversation
+
+Never ask the user to clarify. If `$ARGUMENTS` contains anything, proceed immediately.
+
+### Step 2: Run Deep Analysis
+
+```bash
+forge workflow analyze "the user's topic" [--models <models>] --json
+```
+
+Omit `--models` if the user didn't specify (defaults to claude-opus).
+
+If the command exits with a non-zero code or returns invalid JSON, report the error to the user and stop. Do not attempt
+to parse partial output or fabricate a response.
+
+### Step 3: Present Analysis
+
+Format the model's deep analysis as a structured response:
+
+0. Resolved model used: from `resolved_models`, include requested model, resolved model ref, provider, proxy, and
+   template
+1. Problem decomposition
+2. Key evidence and considerations
+3. Analysis and trade-offs
+4. Recommendations with rationale
+
+If the model failed, report the error and suggest retrying.
+
+**Output routing:** If `--output` was specified, write the complete analysis to that path using the Write tool (create
+parent directories if needed). Print a one-line confirmation: `Wrote analysis to {path}`. Do not also print the full
+result in the conversation. If `--output` was not specified, print the result in the conversation as usual.
+
+---
+
+## Requirements
+
+- **Forge CLI**: `forge` must be on PATH
+- **Claude CLI**: workflow workers run through local `claude -p`; `claude` must be on PATH in this Bash environment
+- **Claude Opus**: Uses direct Anthropic (no proxy needed)

forge/_extensions/skills/challenge/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: forge:challenge
+description: Pressure-test a claim, recommendation, or assumption. Defaults to skepticism.
+argument-hint: '[claim or objection]'
+effort: high
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Challenge
+
+Pressure-test a claim, recommendation, or assumption with adversarial skepticism.
+
+## Usage
+
+```
+/forge:challenge [claim]
+```
+
+## Arguments
+
+| Argument | Required | Description                                                            |
+| -------- | -------- | ---------------------------------------------------------------------- |
+| `claim`  | Optional | Statement, objection, or question to pressure-test (inferred if empty) |
+
+---
+
+## Execution
+
+### Step 1: Resolve Claim
+
+`$ARGUMENTS` is the claim to challenge. It should be a statement, objection, question, or instruction -- not a bare file
+path. If it starts with `@`, strip the prefix (Claude Code file reference syntax).
+
+If `$ARGUMENTS` is empty, infer the claim from the immediately preceding conversation context: the last recommendation,
+decision, assertion, or proposed change. Only ask the user what to challenge if no prior claim is identifiable from
+context.
+
+Never ask the user to clarify if a claim was provided. If `$ARGUMENTS` contains anything, proceed immediately.
+
+### Step 2: Challenge
+
+This skill defaults to **skepticism, not balance**. The starting posture is adversarial: assume the claim may be wrong
+and try to prove that. Only soften to a balanced conclusion if the skeptical case genuinely fails.
+
+If the challenge starts from a neutral or symmetrical frame, it provides no value over a standard analysis. The entire
+point is targeted pressure-testing.
+
+Execute these steps:
+
+1. **Restate the claim precisely.** What exactly is being asserted? Remove ambiguity.
+
+2. **Assume it is wrong.** Actively search for:
+
+   - Flaws in reasoning or hidden assumptions
+   - Counterexamples from the codebase or known constraints
+   - Missing edge cases or failure modes
+   - Simpler alternatives that would invalidate the complexity
+   - Contradictions with existing architecture or decisions
+
+3. **Investigate the repo.** Use Read, Grep, and Glob to find evidence. Check whether the claim holds against actual
+   code, tests, configuration, and documented decisions. Do not reason from first principles alone when evidence is
+   available.
+
+4. **Test the skeptical case.** Is the counterargument strong, or does it fall apart under scrutiny?
+
+5. **If the skeptical case fails,** explain clearly why the original claim survives. This is a valid and useful outcome
+   -- the claim is stronger for having been tested.
+
+6. **Return a verdict:**
+
+   - **Concern validated** -- the skeptical case holds; the claim has real problems
+   - **Partially validated** -- some aspects hold, others don't; specific issues identified
+   - **Concern not supported** -- the skeptical case failed; the claim survives scrutiny
+   - **Insufficient evidence** -- cannot determine either way from available information
+
+### Step 3: Format Output
+
+Present the challenge as:
+
+```
+## Challenge: [restated claim]
+
+### Skeptical Case
+[The strongest argument against the claim, with evidence]
+
+### Counter-Evidence
+[What supports the claim, why the skeptical case fails (if it does)]
+
+### Verdict: [verdict]
+[1-2 sentence summary of the conclusion]
+```

forge/_extensions/skills/consensus/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: forge:consensus
+description: Multi-model consensus workflow. Role-assigned models converge toward a shared recommendation through two rounds of evaluation and reconciliation.
+disable-model-invocation: true
+argument-hint: '[subject: path or proposal or instruction] [--output path] [--code] [--models m1,m2] [--worker model:role]'
+context: fork
+effort: high
+allowed-tools: Bash, Read
+---
+
+# Consensus Workflow
+
+Run a multi-model consensus workflow where role-assigned models build a shared recommendation through two rounds of
+evaluation and reconciliation.
+
+When invoked from Claude Code, execute the workflow now. Do not just restate these instructions, say "Command
+completed", or ask the user to run the commands manually unless a real prerequisite is missing.
+
+## Usage
+
+```
+/forge:consensus [subject] [--code] [--models model1,model2] [--worker model:role]
+```
+
+## Arguments
+
+| Argument   | Required | Description                                                                        |
+| ---------- | -------- | ---------------------------------------------------------------------------------- |
+| `subject`  | Optional | File, directory, proposal, or instruction on what to evaluate (defaults to cwd)    |
+| `--code`   | Optional | Switch: use code evaluation framework (default: proposal)                          |
+| `--models` | Optional | Comma-separated model list (default: Forge workflow defaults)                      |
+| `--worker` | Optional | Repeatable: model:role or model:"custom prompt" (mutually exclusive with --models) |
+| `--output` | Optional | Write result to file instead of conversation (e.g., `consensus.md`)                |
+
+**Available models:** !`forge workflow list-models`
+
+Only use models with status **ready** in the table above. If the default set includes unavailable models, pass
+`--models <ready models>` explicitly. If the user explicitly requested an unavailable model, stop and tell them what
+proxy or credential is missing rather than silently substituting. If no models are ready, tell the user what's missing
+and stop.
+
+---
+
+## Execution
+
+### Step 1: Resolve Subject and Flags
+
+Parse `$ARGUMENTS` into a positional subject and optional flags. The subject is everything that is not a recognized flag
+(file path, directory, proposal text, or free-form instruction). Strip any leading `@` prefix on the subject. If no
+subject is found, default to the current working directory.
+
+Recognized flags (extract from `$ARGUMENTS` if present):
+
+- `--code` -- switch
+- `--models <value>` -- comma-separated model list (mutually exclusive with --worker)
+- `--worker <value>` -- repeatable: model:role or model:custom prompt
+- `--output <path>` -- write result to file instead of conversation
+
+Never ask the user to clarify. If `$ARGUMENTS` contains anything, proceed immediately.
+
+### Step 2: Run Consensus Workflow
+
+```bash
+forge workflow consensus "<subject>" [--code] [--models <models>] [--worker <spec>]... --json
+```
+
+Omit any flag the user didn't specify. Do not pass both `--models` and `--worker`.
+
+Parse the JSON output. The workflow runs two rounds:
+
+- **Round 1**: Each model independently evaluates the subject from their assigned role
+- **Round 2**: Each model receives all Round 1 positions and produces a reconciled recommendation
+- **Resolved models**: The `resolved_models` object records the requested model, actual routed model ref, provider,
+  proxy, template, and role for each worker
+
+If the command fails, surface the real error and stop; do not claim success.
+
+### Step 3: Synthesize
+
+Read `${CLAUDE_SKILL_DIR}/resources/synthesis.md` for synthesis instructions.
+
+Apply the synthesis rules to produce a unified consensus report from both rounds of results. Start the report with a
+"Resolved Models Used" section listing each worker from `resolved_models`, including requested model, resolved model
+ref, provider, proxy, template, and role.
+
+**Output routing:** If `--output` was specified, write the complete synthesis to that path using the Write tool (create
+parent directories if needed). Print a one-line confirmation: `Wrote synthesis to {path}`. Do not also print the full
+result in the conversation. If `--output` was not specified, print the result in the conversation as usual.
+
+---
+
+## Models and Roles
+
+Models are assigned roles cyclically. Default roles differ by mode:
+
+**Proposal mode** (default):
+
+| Order | Default Model          | Role         | Focus                                        |
+| ----- | ---------------------- | ------------ | -------------------------------------------- |
+| 1st   | gpt-5.5                | architecture | Structural alignment, coupling, abstractions |
+| 2nd   | gemini-3.1-pro-preview | security     | Vulnerabilities, trust boundaries, risks     |
+| 3rd   | claude-opus            | correctness  | Logic errors, edge cases, invariants         |
+
+**Code mode** (`--code`):
+
+| Order | Default Model          | Role            | Focus                                  |
+| ----- | ---------------------- | --------------- | -------------------------------------- |
+| 1st   | gpt-5.5                | architecture    | Component boundaries, dependency flow  |
+| 2nd   | gemini-3.1-pro-preview | security        | Injection, auth, secrets, trust        |
+| 3rd   | claude-opus            | maintainability | Readability, complexity, test coverage |
+
+Use `--models` to control which models participate. Use `--worker` for explicit model:role mapping.
+
+**Available named roles:** architecture, security, correctness, maintainability, performance
+
+## Requirements
+
+- **Forge CLI**: `forge` must be on PATH
+- **Claude CLI**: workflow workers run through local `claude -p`; `claude` must be on PATH in this Bash environment
+- **Proxies**: GPT-5.5 and Gemini require active proxies (`forge proxy create openrouter-openai`)

forge/_extensions/skills/consensus/resources/code_consensus_evaluation.md

@@ -0,0 +1,94 @@
+# Code Consensus Evaluation
+
+```xml
+<role>
+You are a senior code evaluator participating in a multi-perspective consensus process.
+{role_prompt}
+You identify issues and opportunities from your assigned perspective.
+You provide actionable feedback with specific code references.
+</role>
+
+<behavior>
+- Read all code in scope before forming opinions
+- Cite specific file:line references for every finding
+- Evaluate from your assigned perspective
+- Support every claim with evidence or reasoning
+- Cover ALL files in ONE pass -- do not present partial results
+- Be specific: "potential null dereference at auth.py:45" not "might have issues"
+- Provide a clear position with confidence level
+</behavior>
+
+<scope_constraints>
+- Review only what's in scope
+- Do not expand to adjacent code unless directly affected
+- If tests exist for reviewed code, check them for coverage gaps
+</scope_constraints>
+```
+
+---
+
+## Code Under Evaluation
+
+{target}
+
+---
+
+## Evaluation Framework
+
+### 1. Quality
+
+- Logic errors and edge cases
+- Error handling: are errors caught, propagated, and surfaced correctly?
+- Type safety: do type annotations match runtime behavior?
+- Test coverage: are critical paths tested?
+
+### 2. Security
+
+- Input validation at trust boundaries
+- Injection vectors (command, SQL, path traversal)
+- Secrets in code or logs
+- Authentication and authorization gaps
+
+### 3. Performance
+
+- Unnecessary allocations or copies in hot paths
+- N+1 query patterns
+- Missing caching where data is reused
+- Blocking calls in async contexts
+
+### 4. Architecture
+
+- Component boundaries: is coupling appropriate?
+- Dependency direction: do imports flow the right way?
+- Abstraction level: is complexity in the right place?
+- Interface contracts: are public APIs stable and well-defined?
+
+### 5. Recommendation
+
+- Your position: SUPPORT, SUPPORT_WITH_CONDITIONS, or OPPOSE
+- Confidence level: LOW, MEDIUM, HIGH
+- Key conditions (if SUPPORT_WITH_CONDITIONS)
+
+---
+
+## Output Format
+
+````xml
+<output_format>
+Respond with your assessment in JSON:
+
+{
+  "position": "SUPPORT" | "SUPPORT_WITH_CONDITIONS" | "OPPOSE",
+  "confidence": "LOW" | "MEDIUM" | "HIGH",
+  "key_points": [
+    {"category": "quality|security|performance|architecture|maintainability",
+     "point": "specific finding with file:line reference",
+     "severity": "critical|high|medium|low"}
+  ],
+  "recommendation": "1-2 sentence summary from your perspective",
+  "conditions": ["condition 1", "condition 2"]
+}
+
+Wrap the JSON in a ```json code fence.
+</output_format>
+````

forge/_extensions/skills/consensus/resources/consensus_evaluation.md

@@ -0,0 +1,70 @@
+# Consensus Evaluation
+
+```xml
+<role>
+You are a technical expert participating in a multi-perspective consensus process.
+{role_prompt}
+</role>
+
+<behavior>
+- Evaluate from your assigned perspective
+- Support every claim with evidence or reasoning
+- Be specific about trade-offs and constraints
+- Identify both strengths and weaknesses from your viewpoint
+- Provide a clear position with confidence level
+</behavior>
+```
+
+---
+
+## Subject Under Evaluation
+
+{subject}
+
+---
+
+## Evaluation Framework
+
+### 1. Assessment from Your Perspective
+
+- What are the key considerations from your assigned viewpoint?
+- What risks or opportunities do you see that others might miss?
+
+### 2. Strengths
+
+- What aspects of this proposal align well with your area of focus?
+
+### 3. Concerns
+
+- What issues or risks do you identify from your perspective?
+- How severe are they? What is the mitigation path?
+
+### 4. Recommendation
+
+- Your position: SUPPORT, SUPPORT_WITH_CONDITIONS, or OPPOSE
+- Confidence level: LOW, MEDIUM, HIGH
+- Key conditions (if SUPPORT_WITH_CONDITIONS)
+
+---
+
+## Output Format
+
+````xml
+<output_format>
+Respond with your assessment in JSON:
+
+{
+  "position": "SUPPORT" | "SUPPORT_WITH_CONDITIONS" | "OPPOSE",
+  "confidence": "LOW" | "MEDIUM" | "HIGH",
+  "key_points": [
+    {"category": "strength|concern|risk|opportunity",
+     "point": "specific finding from your perspective",
+     "severity": "critical|high|medium|low"}
+  ],
+  "recommendation": "1-2 sentence summary from your perspective",
+  "conditions": ["condition 1", "condition 2"]
+}
+
+Wrap the JSON in a ```json code fence.
+</output_format>
+````

forge/_extensions/skills/consensus/resources/synthesis.md

@@ -0,0 +1,101 @@
+# Consensus Synthesis Instructions
+
+You have received results from a two-round consensus workflow. Round 1 contains independent positions from role-assigned
+models. Round 2 contains reconciled recommendations after each model reviewed all Round 1 positions.
+
+Your task is to synthesize these into a unified consensus report.
+
+**Key principle**: The reconciliation process -- how and whether models converged -- is as valuable as the final
+positions. Surface the dynamics, not just the outcomes.
+
+## Synthesis Framework
+
+### 1. Identify Points of Agreement
+
+Recommendations that ALL perspectives converged on during reconciliation (Round 2). These are high-confidence findings.
+
+```markdown
+## Agreed Recommendations (High Confidence)
+
+- **[Recommendation]** (all perspectives agree)
+  - Evidence: [supporting reasoning from multiple roles]
+```
+
+### 2. Identify Partial Agreement
+
+Recommendations where MOST perspectives agree but with different emphasis or conditions:
+
+```markdown
+## Partially Agreed (Moderate Confidence)
+
+- **[Recommendation]**
+  - Agreeing: [roles that support]
+  - Dissenting: [role] -- [reason for different emphasis]
+  - Conditions: [if applicable]
+```
+
+### 3. Identify Remaining Disagreements
+
+Points where consensus was NOT reached after reconciliation. This should be the most detailed section -- remaining
+disagreements expose genuine analytical uncertainty and are often the most valuable findings for the reader.
+
+For each unresolved point:
+
+- Which perspectives disagree and why
+- How positions shifted (or hardened) between Round 1 and Round 2
+- Which position has stronger evidence
+- Whether the disagreement is fundamental or a matter of emphasis
+- What the disagreement reveals about the underlying problem's complexity
+
+```markdown
+## No Consensus
+
+- **[Point of disagreement]**
+  - [Role A]: [position and reasoning]
+  - [Role B]: [position and reasoning]
+  - Assessment: [which has stronger evidence, or why this is genuinely unresolvable]
+```
+
+**Convergence dynamics**: For each recommendation in sections 1-3, briefly note how positions shifted between rounds.
+Did Round 2 reconciliation move perspectives closer, or did it sharpen the disagreement? The trajectory matters as much
+as the final position.
+
+### 4. Final Recommendation
+
+Based on the synthesis above:
+
+- If full consensus: State the shared recommendation with confidence level
+- If partial consensus: State what was agreed, flag what was not, recommend which disputed position to follow and why
+- If no consensus: Explicitly state "NO CONSENSUS" and explain the fundamental disagreements that prevented convergence
+
+### 5. Confidence Assessment
+
+- Consensus strength: strong | moderate | weak | none
+- What would strengthen the consensus?
+- What caveats apply?
+
+## Output Format
+
+```markdown
+# Consensus Report: [Subject]
+
+## Summary
+- Models consulted: N
+- Roles: [list]
+- Consensus strength: strong|moderate|weak|none
+
+## Agreed Recommendations (High Confidence)
+[...]
+
+## Partially Agreed (Moderate Confidence)
+[...]
+
+## No Consensus
+[...]
+
+## Overall Recommendation
+[...]
+
+## Confidence and Caveats
+[...]
+```

forge/_extensions/skills/debate/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: forge:debate
+description: Adversarial multi-model evaluation. Models argue for, against, and neutrally about a subject.
+disable-model-invocation: true
+argument-hint: '[subject: path or proposal or instruction] [--output path] [--code] [--models m1,m2] [--worker model:stance]'
+context: fork
+effort: high
+allowed-tools: Bash, Read
+---
+
+# Debate Evaluation
+
+Run an adversarial multi-model evaluation where models argue for, against, and neutrally about a subject.
+
+When invoked from Claude Code, execute the workflow now. Do not just restate these instructions, say "Command
+completed", or ask the user to run the commands manually unless a real prerequisite is missing.
+
+## Usage
+
+```
+/forge:debate [subject] [--code] [--models model1,model2]
+```
+
+## Arguments
+
+| Argument   | Required | Description                                                                          |
+| ---------- | -------- | ------------------------------------------------------------------------------------ |
+| `subject`  | Optional | File, directory, proposal, or instruction on what to evaluate (defaults to cwd)      |
+| `--code`   | Optional | Switch: use code evaluation framework (default: proposal)                            |
+| `--models` | Optional | Comma-separated model list (default: Forge workflow defaults)                        |
+| `--worker` | Optional | Repeatable: model:stance or model:"custom prompt" (mutually exclusive with --models) |
+| `--output` | Optional | Write result to file instead of conversation (e.g., `debate.md`)                     |
+
+**Available models:** !`forge workflow list-models`
+
+Only use models with status **ready** in the table above. If the default set includes unavailable models, pass
+`--models <ready models>` explicitly. If the user explicitly requested an unavailable model, stop and tell them what
+proxy or credential is missing rather than silently substituting. If no models are ready, tell the user what's missing
+and stop.
+
+---
+
+## Execution
+
+### Step 1: Resolve Subject and Flags
+
+Parse `$ARGUMENTS` into a positional subject and optional flags. The subject is everything that is not a recognized flag
+(file path, directory, proposal text, or free-form instruction). Strip any leading `@` prefix on the subject. If no
+subject is found, default to the current working directory.
+
+Recognized flags (extract from `$ARGUMENTS` if present):
+
+- `--code` — switch
+- `--models <value>` — comma-separated model list (mutually exclusive with --worker)
+- `--worker <value>` — repeatable: model:stance or model:custom prompt
+- `--output <path>` — write result to file instead of conversation
+
+Never ask the user to clarify. If `$ARGUMENTS` contains anything, proceed immediately.
+
+### Step 2: Run Adversarial Evaluation
+
+```bash
+forge workflow debate "<subject>" [--code] [--models <models>] [--worker <spec>]... --json
+```
+
+Omit any flag the user didn't specify. Do not pass both `--models` and `--worker`.
+
+Parse the JSON output. Each model receives a different stance (for/against/neutral) and evaluates the subject from that
+perspective. The `resolved_models` object records the requested model, actual routed model ref, provider, proxy,
+template, and stance for each worker. If the command fails, surface the real error and stop; do not claim success.
+
+### Step 3: Synthesize
+
+Combine the perspectives:
+
+0. **Resolved models used**: one line per worker from `resolved_models`, including requested model, resolved model ref,
+   provider, proxy, template, and stance
+1. **Points of agreement** across all stances
+2. **Key disagreements** and which stance has stronger evidence
+3. **Risk assessment** from the critic's perspective
+4. **Viability assessment** from the supporter's perspective
+5. **Overall recommendation** with confidence level
+
+Make it clear which parts came from agreement across stances versus which parts remain disputed.
+
+**Output routing:** If `--output` was specified, write the complete synthesis to that path using the Write tool (create
+parent directories if needed). Print a one-line confirmation: `Wrote synthesis to {path}`. Do not also print the full
+result in the conversation. If `--output` was not specified, print the result in the conversation as usual.
+
+---
+
+## Models and Roles
+
+Models are assigned stances cyclically. Default models:
+
+| Order | Default Model          | Stance  | Role                     |
+| ----- | ---------------------- | ------- | ------------------------ |
+| 1st   | gpt-5.5                | FOR     | Supporter -- strengths   |
+| 2nd   | gemini-3.1-pro-preview | AGAINST | Critic -- risks          |
+| 3rd   | claude-opus            | NEUTRAL | Analyst -- balanced view |
+
+Use `--models` to control which models participate. Stances cycle through for/against/neutral in order.
+
+## Code Mode
+
+When `--code` is specified, models evaluate the target code from adversarial perspectives:
+
+- **FOR** stance: Identifies good design, correct implementations, production readiness
+- **AGAINST** stance: Identifies bugs, security issues, performance problems, architectural flaws
+- **NEUTRAL** stance: Balanced assessment of code quality with file:line evidence
+
+## Requirements
+
+- **Forge CLI**: `forge` must be on PATH
+- **Claude CLI**: workflow workers run through local `claude -p`; `claude` must be on PATH in this Bash environment
+- **Proxies**: GPT-5.5 and Gemini require active proxies (`forge proxy create openrouter-openai`)