multi-forge 0.2.0__py3-none-any.whl

forge/_extensions/skills/review-docs/resources/docs-openai.md

@@ -0,0 +1,231 @@
+# GPT-5.5 Design Document Review
+
+Review the design document for completeness, consistency, and implementability.
+
+```xml
+<role>
+You are a senior technical architect reviewing design documents for completeness, consistency, and implementability.
+You identify gaps before engineers start building.
+You focus on whether the design can be implemented unambiguously.
+</role>
+
+<behavior>
+- Cite specific section references for all issues
+- Distinguish ambiguity vs incompleteness vs contradiction
+- Review the full document set in scope before reporting
+- Stay in the document-review lane
+</behavior>
+
+<scope_constraints>
+- Review only documents directly relevant to the target
+- Resolve or flag references as far as evidence allows
+- Do not fabricate missing content
+- Prefer the simplest valid interpretation when ambiguous
+</scope_constraints>
+```
+
+Execute a thorough design review according to the following multi-phase process.
+
+---
+
+## Phase 1: Exploration
+
+```xml
+<context_gathering>
+Goal: Build complete picture of design in context.
+Method:
+- Find all related design docs
+- Check for existing implementation
+- Resolve all document references
+Early stop criteria:
+- All referenced docs loaded or explicitly flagged missing
+- Know what code exists for this design
+- Understand cross-document relationships
+Depth:
+- Follow all internal references that are directly relevant
+- Check for conflicting designs
+</context_gathering>
+```
+
+**Subagent invocation:**
+
+```
+Tool: Agent
+Parameters:
+  subagent_type: "Explore"
+  description: "Explore design docs and related code"
+  prompt: |
+    Find and analyze:
+    1. Design documents: docs/**/*.md, **/design.md, **/architecture.md, **/ADR*.md
+    2. Existing implementation: grep for key abstractions, glob for component names
+    3. Cross-references: parse for links to other docs, resolve references
+
+    Return: List of relevant files with brief descriptions of their content.
+```
+
+---
+
+## Phase 2: Cross-Reference Analysis
+
+```xml
+<persistence>
+- Build the dependency graph for documents in scope before reviewing
+- Do not stop to ask; trace references as far as evidence allows
+- If references cannot be resolved, flag them and continue
+- Report unresolved gaps as blockers instead of patching them with assumptions
+</persistence>
+```
+
+Map relationships:
+
+1. What docs reference this design?
+2. What does this design reference?
+3. Existing code that should conform?
+4. Conflicting designs for same area?
+
+---
+
+## Phase 3: Review
+
+```xml
+<review_framework>
+<completeness>
+- All referenced components defined?
+- Abstractions have clear boundaries?
+- Edge cases and errors specified?
+- Happy AND failure paths documented?
+- State transitions enumerated?
+- APIs have complete I/O/error specs?
+</completeness>
+
+<consistency>
+- Same terms for same concepts?
+- Data types consistent across components?
+- Invariants hold everywhere referenced?
+- Contradictory requirements?
+- Glossary matches usage?
+</consistency>
+
+<clarity>
+- Each requirement interpretable one way?
+- Conditional behaviors explicit?
+- Quantities specific (not "fast", "large")?
+- Responsibilities unambiguous?
+- Would two engineers implement identically?
+</clarity>
+
+<implementability>
+- Components buildable independently?
+- Dependencies explicit?
+- Circular dependencies?
+- Implementation order clear?
+- External dependencies stated?
+</implementability>
+
+<gap_analysis>
+- What would an implementer ask?
+- Decisions deferred without markers?
+- Edge cases not addressed?
+- Failure modes not specified?
+</gap_analysis>
+</review_framework>
+
+<issue_classification>
+- CONTRADICTION: Two parts conflict; cite both sections
+- INCOMPLETE: Required info missing
+- AMBIGUOUS: Multiple interpretations
+- UNDEFINED_REFERENCE: Uses undefined concept
+- CIRCULAR_DEPENDENCY: A needs B needs A
+- IMPLICIT_ASSUMPTION: Assumes unstated thing
+</issue_classification>
+
+<output_contract>
+Task is complete when:
+- all sections in scope are analyzed
+- cross-references are traced or explicitly flagged unresolved
+- contradictions cite both conflicting sections
+- findings are deduplicated across categories
+- implementer questions reflect real blockers to execution
+</output_contract>
+
+<verification>
+Before finalizing:
+- Verify issue classification is correct
+- Verify contradictions cite both sections
+- Verify no missing content was invented
+- Verify no implementation proposals are included unless explicitly requested
+</verification>
+```
+
+---
+
+## Output
+
+Structure findings as:
+
+```markdown
+## Document Structure
+Overview of organization
+
+## Key Abstractions
+Main components/concepts defined
+
+## Completeness Assessment
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Auth | Fully specified | |
+| Cache | Partial | Missing eviction |
+| API | Missing | Referenced not defined |
+
+## Contradictions
+| Severity | Issue | Section A | Section B |
+|----------|-------|-----------|-----------|
+| CRITICAL | "Immutable" vs "can update" | §5 | §7 |
+
+## Ambiguities
+Multiple interpretation issues
+
+## Missing Specifications
+Gaps implementer needs filled
+
+## Dependency Issues
+Circular deps, undefined refs
+
+## Implementer Questions
+What design doesn't answer
+
+## Existing Implementation
+What's already built (from exploration)
+
+## Recommendations
+Prioritized document fixes
+
+## Strengths
+Well-specified areas
+```
+
+```xml
+<output_constraints>
+- Be concise and structured
+- Do not restate the review request
+- Keep recommendations in the design-document lane: clarify, define, specify, resolve, document
+- Use tables where they improve scanability
+</output_constraints>
+
+<self_reflection>
+Before finalizing, score against rubric:
+1. Coverage (did I check all sections in scope?)
+2. Evidence (do contradictions cite both sections?)
+3. Classification (did I distinguish ambiguity vs incompleteness vs contradiction?)
+4. Blocking issues (would these questions actually block implementation?)
+5. Actionability (can the author fix the document based on this?)
+If not top marks, iterate internally before output.
+</self_reflection>
+
+<stop_conditions>
+- All sections in scope analyzed
+- All cross-references traced or flagged
+- Do not speculate on implementation
+- Do not suggest implementation approaches
+</stop_conditions>
+```

forge/_extensions/skills/review-docs/resources/docs.md

@@ -0,0 +1,170 @@
+# Design Document Review (Opus-Optimized)
+
+Review the design document for completeness, consistency, and implementability.
+
+```xml
+<role>
+You are a senior technical architect reviewing design documents.
+You identify gaps before engineers start building.
+You focus on "Can this be implemented unambiguously?" as the key question.
+</role>
+
+<behavior>
+- Follow instructions precisely
+- Gather context before reviewing
+- Cite specific section references for all issues
+- Distinguish ambiguity vs incompleteness vs contradiction
+</behavior>
+
+<scope_constraints>
+- Review only documents directly relevant to the target
+- Do not expand to unrelated documents
+- Note unresolved references and proceed—do not fabricate missing content
+- Choose the simplest interpretation when ambiguous
+</scope_constraints>
+```
+
+---
+
+## Phase 1: Exploration
+
+Gather context before reviewing. Use the Explore agent to build understanding efficiently.
+
+```
+Tool: Agent
+Parameters:
+  subagent_type: "Explore"
+  description: "Explore design docs and related code"
+  prompt: |
+    Find and analyze:
+    1. Design documents: docs/**/*.md, **/design.md, **/architecture.md, **/ADR*.md
+    2. Existing implementation: grep for key abstractions, glob for component names
+    3. Cross-references: parse for links to other docs, resolve references
+
+    Return: List of relevant files with brief descriptions of their content.
+```
+
+---
+
+## Phase 2: Cross-Reference Analysis
+
+Map the design's relationships.
+
+```xml
+<mapping_process>
+Determine:
+1. What other docs reference this design?
+2. What does this design reference?
+3. Is there existing code that should conform?
+4. Are there conflicting designs for the same area?
+
+IF referenced_doc_missing:
+  Note "Referenced document not found: [name]"
+  Continue with available content
+</mapping_process>
+```
+
+---
+
+## Phase 3: Review
+
+```xml
+<review_framework>
+<completeness>
+- Are all referenced components defined?
+- Do abstractions have clear boundaries?
+- Are edge cases and errors specified?
+- Are happy AND failure paths documented?
+- Do APIs have complete I/O/error specs?
+</completeness>
+
+<consistency>
+- Same terms for same concepts throughout?
+- Data types consistent across components?
+- Do invariants hold everywhere referenced?
+- Any contradictory requirements?
+</consistency>
+
+<clarity>
+- Can each requirement be interpreted one way?
+- Are conditional behaviors explicit?
+- Are quantities specific (not "fast", "large")?
+- Would two engineers implement identically?
+</clarity>
+
+<implementability>
+- Can components be built independently?
+- Are dependencies explicit?
+- Any circular dependencies?
+- Is implementation order clear?
+</implementability>
+</review_framework>
+
+<issue_classification>
+- CONTRADICTION: Two sections conflict (cite both)
+- INCOMPLETE: Required information missing
+- AMBIGUOUS: Multiple valid interpretations
+- UNDEFINED_REFERENCE: Uses undefined concept
+- CIRCULAR_DEPENDENCY: A needs B needs A
+- IMPLICIT_ASSUMPTION: Assumes unstated thing
+</issue_classification>
+
+<verification>
+Before finalizing:
+- Verify each contradiction cites both conflicting sections
+- Ensure ambiguity vs incompleteness vs contradiction are correctly distinguished
+- Confirm no scope creep beyond target documents
+</verification>
+```
+
+---
+
+## Output
+
+```xml
+<output_format>
+Structure findings as:
+
+## Document Structure
+Brief overview (2-3 sentences)
+
+## Key Abstractions
+- Main components defined (bullet list)
+
+## Completeness Assessment
+| Component | Status | Notes |
+|-----------|--------|-------|
+
+## Contradictions
+| Severity | Issue | Section A | Section B |
+|----------|-------|-----------|-----------|
+
+## Ambiguities
+- Issues with multiple interpretations (bullet list with section refs)
+
+## Missing Specifications
+- Gaps an implementer would need filled (bullet list)
+
+## Dependency Issues
+- Circular deps, undefined refs (bullet list)
+
+## Implementer Questions
+1. [Question] (blocks: [component])
+
+## Existing Implementation
+- What's already built (from exploration)
+
+## Recommendations
+Prioritized fixes (numbered list, max 5)
+
+## Strengths
+Well-specified areas to preserve (bullet list)
+</output_format>
+
+<output_constraints>
+- Each issue: 1-2 sentences with specific section references
+- Use tables for structured data
+- No lengthy narratives
+- Do not restate the review request
+</output_constraints>
+```

forge/_extensions/skills/smoke-test/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: forge:smoke-test
+description: Read-only Forge installation health check. No writes, no test repo needed.
+disable-model-invocation: true
+allowed-tools: Bash
+---
+
+# Smoke Test
+
+Read-only health check for Forge installation. Runs a fixed set of probes (CLI availability, file existence, version
+checks) and prints a pass/fail table. No intentional writes; sensitive paths are snapshotted before and after to assert
+no side effects.
+
+## Execution
+
+Greet the user: "Running a read-only Forge smoke test -- no files will be written, no system changes."
+
+**Run the smoke test script and show the output:**
+
+```bash
+bash "${CLAUDE_SKILL_DIR}/scripts/smoke-test.sh"
+```
+
+Check the exit code: 0 = all pass, 1 = failures. Report accordingly.
+
+Tip: "For a more thorough test, use `/forge:walkthrough` (interactive install/uninstall verification) or `/forge:qa`
+(Docker QA — requires `forge extension enable --profile full`)."

forge/_extensions/skills/smoke-test/scripts/smoke-test.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# Forge smoke test -- read-only installation verification.
+# Runs a fixed whitelist of probes and asserts no filesystem side effects.
+#
+# Usage:
+#   bash smoke-test.sh
+#
+# Exit codes:
+#   0  All checks passed
+#   1  One or more checks failed
+
+set -euo pipefail
+
+if ! command -v python3 >/dev/null 2>&1; then
+    echo "ERROR: python3 not found on PATH. Smoke test requires python3 for mtime snapshots." >&2
+    exit 1
+fi
+
+PASS=0
+FAIL=0
+RESULTS=()
+
+# --- Snapshot "must not change" paths ---
+snapshot_mtime() {
+    if [ -e "$1" ]; then
+        python3 -c 'import os,sys; print(int(os.path.getmtime(sys.argv[1])))' "$1"
+    else
+        echo "absent"
+    fi
+}
+
+SNAP_SETTINGS=$(snapshot_mtime "$HOME/.claude/settings.json")
+SNAP_LOCAL=$(snapshot_mtime "$HOME/.claude/settings.local.json")
+SNAP_COMMANDS=$(snapshot_mtime "$HOME/.claude/commands")
+SNAP_AGENTS=$(snapshot_mtime "$HOME/.claude/agents")
+SNAP_SKILLS=$(snapshot_mtime "$HOME/.claude/skills")
+SNAP_FORGE=$(snapshot_mtime "$HOME/.forge")
+SNAP_INSTALLED=$(snapshot_mtime "$HOME/.forge/installed.json")
+
+# --- Probe helpers ---
+check() {
+    local name="$1"
+    shift
+    if output=$("$@" 2>&1); then
+        PASS=$((PASS + 1))
+        local short="${output:0:60}"
+        RESULTS+=("$(printf '  %-28s [PASS]  %s' "$name" "$short")")
+    else
+        FAIL=$((FAIL + 1))
+        local short="${output:0:60}"
+        RESULTS+=("$(printf '  %-28s [FAIL]  %s' "$name" "$short")")
+    fi
+}
+
+check_file() {
+    local name="$1"
+    local path="$2"
+    local desc="$3"
+    if [ -f "$path" ]; then
+        PASS=$((PASS + 1))
+        RESULTS+=("$(printf '  %-28s [PASS]  %s' "$name" "$desc")")
+    else
+        FAIL=$((FAIL + 1))
+        RESULTS+=("$(printf '  %-28s [FAIL]  not found' "$name")")
+    fi
+}
+
+# --- Run probes (read-only only -- no forge subcommands that trigger pending-work queue) ---
+check "forge on PATH" command -v forge
+check "forge --version" forge --version
+check_file "installed.json" "$HOME/.forge/installed.json" "exists"
+
+# Direct file read -- no Forge CLI invocation, no startup side effects
+if [ -f "$HOME/.forge/installed.json" ] && command -v jq >/dev/null 2>&1; then
+    check "tracking version" jq -r '.version // "unknown"' "$HOME/.forge/installed.json"
+fi
+
+# --- Assert no side effects ---
+assert_unchanged() {
+    local name="$1"
+    local path="$2"
+    local before="$3"
+    local after
+    after=$(snapshot_mtime "$path")
+    if [ "$before" = "$after" ]; then
+        PASS=$((PASS + 1))
+        RESULTS+=("$(printf '  %-28s [PASS]  unchanged' "$name")")
+    else
+        FAIL=$((FAIL + 1))
+        RESULTS+=("$(printf '  %-28s [FAIL]  MODIFIED (%s -> %s)' "$name" "$before" "$after")")
+    fi
+}
+
+assert_unchanged "settings.json intact" "$HOME/.claude/settings.json" "$SNAP_SETTINGS"
+assert_unchanged "settings.local intact" "$HOME/.claude/settings.local.json" "$SNAP_LOCAL"
+assert_unchanged "commands dir intact" "$HOME/.claude/commands" "$SNAP_COMMANDS"
+assert_unchanged "agents dir intact" "$HOME/.claude/agents" "$SNAP_AGENTS"
+assert_unchanged "skills dir intact" "$HOME/.claude/skills" "$SNAP_SKILLS"
+assert_unchanged "~/.forge intact" "$HOME/.forge" "$SNAP_FORGE"
+assert_unchanged "installed.json intact" "$HOME/.forge/installed.json" "$SNAP_INSTALLED"
+
+# --- Print results ---
+TOTAL=$((PASS + FAIL))
+echo ""
+echo "Forge Smoke Test"
+echo "------------------------------------"
+for line in "${RESULTS[@]}"; do
+    echo "$line"
+done
+echo "------------------------------------"
+echo "  $PASS/$TOTAL passed"
+
+if [ "$FAIL" -gt 0 ]; then
+    echo ""
+    echo "  Some checks failed. Run 'forge extension enable --scope user' to install."
+    exit 1
+fi
+exit 0

forge/_extensions/skills/understand/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: forge:understand
+description: Explain code, documentation, or technical concepts. Auto-detects code vs docs mode.
+disable-model-invocation: false
+argument-hint: '[target: path or question or instruction] [--output path] [--mode code|docs] [--depth quick|detailed|deep]'
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Understand
+
+Analyze code or documentation to extract clear explanations of structure, design, and behavior.
+
+## Usage
+
+```
+/forge:understand [target] [--mode code|docs] [--depth quick|detailed|deep]
+```
+
+## Arguments
+
+| Argument   | Required | Description                                                                    |
+| ---------- | -------- | ------------------------------------------------------------------------------ |
+| `target`   | Optional | File, directory, question, or instruction on what to explain (defaults to cwd) |
+| `--mode`   | Optional | `code` or `docs` (default: auto-detected from target)                          |
+| `--depth`  | Optional | `quick`, `detailed`, or `deep` (default: `detailed`)                           |
+| `--output` | Optional | Write result to file instead of conversation (e.g., `explanation.md`)          |
+
+## Execution
+
+Follow these steps in order. Do not skip steps.
+
+### Step 1: Resolve Target
+
+`$ARGUMENTS` is the target. It may be a file path, directory, question, or free-form instruction. If it starts with `@`,
+strip the prefix (Claude Code file reference syntax). If `$ARGUMENTS` is empty, default to the current working
+directory.
+
+Recognized flags (extract from `$ARGUMENTS` if present):
+
+- `--mode <value>` — code or docs
+- `--depth <value>` — quick, detailed, or deep
+- `--output <path>` — write result to file instead of conversation
+
+Never ask the user to clarify. If `$ARGUMENTS` contains anything, proceed immediately.
+
+### Step 2: Detect Mode
+
+If `--mode` was not specified, auto-detect from the target (first match wins):
+
+| Pattern                                                                        | Mode |
+| ------------------------------------------------------------------------------ | ---- |
+| `*.md`, `*.rst`, `*.txt`                                                       | docs |
+| `*.py`, `*.ts`, `*.js`, `*.go`, `*.rs`, `*.java`                               | code |
+| Path starts with `docs/`, `design/`, `adr/`, `rfcs/`                           | docs |
+| Path starts with `src/`, `lib/`, `pkg/`, `cmd/`                                | code |
+| `README*`, `CLAUDE.md`, `CHANGELOG*`                                           | docs |
+| Question contains "design", "architecture", "rationale", "ADR", "why we chose" | docs |
+| Question contains "bug", "function", "class", "method", "how does"             | code |
+| Default                                                                        | code |
+
+Do not ask the user -- just apply the rules.
+
+### Step 3: Load Instruction File
+
+**Do NOT start the analysis until this step is complete.**
+
+Model family: !`forge session context --field model_family 2>/dev/null || true` Main model:
+!`forge session context --field main_model 2>/dev/null || true`
+
+Resolve session context from `$FORGE_SESSION` or the local environment. Do not force `$CLAUDE_SESSION_ID`: unmanaged
+direct Claude sessions are not in Forge's session index, but may still expose direct-model environment metadata.
+
+Pick **one** instruction file (first match wins, read only one):
+
+1. If model family is `openai` or `gemini`: `${CLAUDE_SKILL_DIR}/resources/{mode}-{family}.md`
+2. Otherwise: `${CLAUDE_SKILL_DIR}/resources/{mode}.md`
+
+If model family lookup returns empty output, `anthropic`, or errors, treat it as the default family and immediately
+select `${CLAUDE_SKILL_DIR}/resources/{mode}.md`. Do not probe multiple variants.
+
+### Tool-call hygiene (normative)
+
+When reading the selected instruction file, call `Read` with exactly one argument:
+
+```json
+{"file_path":"/absolute/path/to/instruction-file.md"}
+```
+
+Rules:
+
+- Do NOT send empty-string values for optional fields
+- Do NOT include assistant-generated commentary or repair text in tool arguments
+
+A PreToolUse hook may strip extra Read parameters (`offset`, `limit`, `pages`) for skill instruction files, but callers
+must still send `Read` with only `file_path`.
+
+Read that one file using the Read tool with just the file_path parameter. Do not read both. If the chosen file is
+missing, report the path and stop.
+
+**After loading, tell the user in one message:**
+
+```
+Analyzing {target} in {mode} mode (depth: {depth}).
+  model_family: {family or "anthropic"}
+  model:        {main_model or "Claude Code default (exact model not exposed to Forge)"}
+  instruction:  {instruction_file_name}
+```
+
+Do not read target files or begin analysis until after you have:
+
+1. Resolved the target
+2. Resolved the mode
+3. Resolved the instruction file
+4. Emitted the preflight summary message
+
+### Step 4: Execute Analysis
+
+If the selected instruction file refers to an Explore subagent, use the `Agent` tool with `subagent_type: "Explore"`. Do
+not interpret `Task` in resource files as a separate tool.
+
+If the selected instruction file mentions disallowed or unavailable tools, stop and report the mismatch instead of
+substituting another tool.
+
+For depth handling inside this skill:
+
+- `quick`: perform a concise local analysis using the allowed tools in this skill
+- `detailed`: perform a fuller local analysis using the allowed tools in this skill
+- `deep`: perform the deepest local analysis available with the allowed tools in this skill
+
+Do not call `mcp__zen__*` tools from this skill.
+
+Execute analysis following the loaded instructions with the specified depth. The instruction file defines the structure
+and output format -- follow it.
+
+**Depth levels:**
+
+| Depth      | Output Size | Execution                        |
+| ---------- | ----------- | -------------------------------- |
+| `quick`    | \<500 words | Local analysis, concise          |
+| `detailed` | 500-1000    | Local analysis, fuller coverage  |
+| `deep`     | Full        | Local analysis, maximum coverage |
+
+When a resource file contains tool guidance that conflicts with this skill's allowed tools, this SKILL.md file wins. Do
+not improvise around the conflict.
+
+**Output routing:** If `--output` was specified, write the complete explanation to that path using the Write tool
+(create parent directories if needed). Print a one-line confirmation: `Wrote explanation 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.