multi-forge 0.2.0__py3-none-any.whl

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

@@ -0,0 +1,121 @@
+---
+name: forge:review-docs
+description: Review design documents, specs, and technical writing for completeness and consistency.
+disable-model-invocation: false
+argument-hint: '[target: path or instruction] [--output path]'
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Document Review
+
+Review design documents, specs, and technical writing for completeness, consistency, clarity, and implementability.
+
+## Usage
+
+```
+/forge:review-docs [target]
+```
+
+## Arguments
+
+| Argument   | Required | Description                                                         |
+| ---------- | -------- | ------------------------------------------------------------------- |
+| `target`   | Optional | File, directory, or instruction on what to review (defaults to cwd) |
+| `--output` | Optional | Write result to file instead of conversation (e.g., `review.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, 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):
+
+- `--output <path>` — write result to file instead of conversation
+
+Never ask the user to clarify. If `$ARGUMENTS` contains anything, proceed immediately.
+
+### Step 2: Load Instruction File
+
+**Do NOT start the review 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/docs-{family}.md`
+2. Otherwise: `${CLAUDE_SKILL_DIR}/resources/docs.md`
+
+If model family lookup returns empty output, `anthropic`, or errors, treat it as the default family and immediately
+select `${CLAUDE_SKILL_DIR}/resources/docs.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:**
+
+```
+Reviewing {target} in docs mode.
+  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 review until after you have:
+
+1. Resolved the target
+2. Resolved the instruction file
+3. Emitted the preflight summary message
+
+### Step 3: Execute Review
+
+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.
+
+Execute the review following the loaded instructions. The instruction file defines the rubric, structure, and output
+format. Do not invent your own review format -- follow what the instruction file says.
+
+Do not call `mcp__zen__*` tools from this skill.
+
+When a resource file contains tool guidance that conflicts with this SKILL.md file, this SKILL.md file wins. Do not
+improvise around the conflict.
+
+**Output routing:** If `--output` was specified, write the complete review to that path using the Write tool (create
+parent directories if needed). Print a one-line confirmation: `Wrote review 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.
+
+## Multi-Model Mode (optional)
+
+For a multi-model perspective, use `forge workflow panel` to get independent document reviews from multiple backends:
+
+```bash
+forge workflow panel [target] --json
+```
+
+Or invoke `/forge:panel` for the full multi-model document review workflow.

forge/_extensions/skills/review-docs/resources/docs-anthropic.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/review-docs/resources/docs-gemini.md

@@ -0,0 +1,204 @@
+# Gemini 3.1 Design Document Review
+
+Review the design document for completeness, consistency, and implementability.
+
+Execute a thorough design review according to the following multi-phase process.
+
+```xml
+<role>
+You are a senior technical architect reviewing design documents.
+You are precise, thorough, and focused on implementability.
+You identify gaps before engineers start building.
+</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>
+```
+
+---
+
+## Phase 1: Exploration
+
+**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
+
+Build understanding of design in context:
+
+1. What other docs reference this design?
+2. What does this design reference?
+3. Is there existing code that should conform to this?
+4. Are there conflicting designs for the same area?
+
+---
+
+## Phase 3: Review
+
+```xml
+<review_framework>
+<completeness>
+- Are all referenced components defined?
+- Do abstractions have clear boundaries?
+- Are edge cases and errors specified?
+- Is happy path AND failure path documented?
+- Are all state transitions enumerated?
+- Do APIs have complete I/O/error specs?
+</completeness>
+
+<consistency>
+- Same terms for same concepts throughout?
+- Data types consistent across components?
+- Invariants hold in all referenced places?
+- Contradictory requirements between sections?
+- Glossary matches actual usage?
+</consistency>
+
+<clarity>
+- Can each requirement be interpreted ONE way?
+- Conditional behaviors explicit (if X then Y)?
+- Quantities specific (not "fast", "large")?
+- Responsibilities unambiguous (who does what)?
+- Would two engineers implement identically?
+</clarity>
+
+<implementability>
+- Can each component be built independently?
+- Dependencies between components explicit?
+- Any circular dependencies?
+- Order of implementation clear?
+- External dependencies stated?
+</implementability>
+
+<gap_analysis>
+- What questions would implementer ask?
+- What decisions deferred without markers?
+- What edge cases not addressed?
+- What failure modes not specified?
+</gap_analysis>
+</review_framework>
+
+<issue_classification>
+- CONTRADICTION: Two parts conflict (cite both sections)
+- INCOMPLETE: Required info missing
+- AMBIGUOUS: Multiple valid interpretations
+- UNDEFINED_REFERENCE: Uses undefined concept
+- CIRCULAR_DEPENDENCY: A needs B needs A
+- IMPLICIT_ASSUMPTION: Assumes unstated thing
+</issue_classification>
+
+<error_handling>
+IF design document empty or unreadable:
+  State "Document could not be analyzed"
+  Explain why
+IF referenced documents missing:
+  Note which references could not be resolved
+  Continue with available content, flagging gaps
+</error_handling>
+
+<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 design doc organization
+
+## Key Abstractions
+Main components/concepts defined
+
+## Completeness Assessment
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Auth module | Fully specified | |
+| Cache layer | Partial | Missing eviction policy |
+| API routes | Missing | Referenced but not defined |
+
+## Contradictions
+| Severity | Issue | Section A | Section B |
+|----------|-------|-----------|-----------|
+| CRITICAL | "Immutable" vs "can update" | §5.2 | §7.1 |
+
+## Ambiguities
+Issues that could be interpreted multiple ways
+
+## Missing Specifications
+Gaps an implementer would need filled
+
+## Dependency Issues
+Circular deps, undefined refs, ordering problems
+
+## Implementer Questions
+Questions the design doesn't answer
+
+## Existing Implementation Status
+What's already built (from exploration)
+
+## Recommendations
+Prioritized fixes to improve the design
+
+## Strengths
+Well-specified areas to preserve
+```
+
+```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>
+
+<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>
+```