Simple Gemini

Gemini Documentation & Test Writer

Overview

This skill provides a collaborative writing workflow where gemini CLI (launched via zen mcp's clink tool as a WSL command gemini) serves as a specialist writer for markdown documentation and test code. All writing operations are executed within the gemini CLI session environment, while the main Claude model handles context gathering, user interaction, and test execution. For test code, codex CLI (also launched via clink as WSL command codex) performs quality validation after gemini completes the initial writing.

Technical Architecture:

• zen-mcp clink: Acts as the bridge to launch CLI tools in WSL environment
• gemini CLI session: Opened via gemini command in WSL, where all document/test writing happens
• codex CLI session: Opened via codex command in WSL for code review tasks
• Conversation context: Maintained via continuation_id across CLI sessions

Division of Responsibilities:

• Gemini CLI Session (in WSL): Specialist writer for .md documents and test code, all writing executed inside this CLI environment
• Main Claude Model: Context gathering, CLI invocation orchestration, outline approval, test execution, final review
• Codex CLI Session (in WSL): Test code quality validation and correction, review executed inside this CLI environment
• User: Approval of outlines and final review (in Interactive Mode) or information recipient (in Automated Mode)

When to Use This Skill

Trigger this skill when the user or main model requests:

• "Use gemini to write test files"
• "Use gemini to write documentation"
• "Generate related test files"
• "Generate an explanatory document"
• Commands from Claude or codex to write documentation
• Any request to create .md documentation or test code files

Operation Mode (automation_mode - READ FROM SSOT)

automation_mode definition and constraints: See CLAUDE.md「📚 共享概念速查」

This skill's role: Skill Layer (read-only), read from context [AUTOMATION_MODE: true/false]

• false → Interactive: Requires user confirmation (outline, review, test corrections)
• true → Automated: Autonomous decisions, escalate only for critical issues, record to auto_log.md

Coverage Target Management (READ ONLY - G9 Compliance)

coverage_target definition and constraints: See CLAUDE.md「📚 共享概念速查」

This skill's role: Skill Layer (read-only), read from context [COVERAGE_TARGET: X%], use when generating/evaluating test code (default 85% if missing)

Workflow Decision Tree

User Request
    │
    ├─→ Document Writing? ──→ Document Writing Workflow
    │
    └─→ Test Code Writing? ──→ Test Code Writing Workflow

Document Writing Workflow

Phase 1: Preparation & Context Gathering (Main Claude)

Main Claude's Responsibility:

1. Understand the Documentation Need:

   • What type of document? (README, PROJECTWIKI, ADR, CHANGELOG, technical spec, etc.)
   • What is the purpose and audience?
   • What scope should be covered?

2. Gather Context:

   • Read relevant code files if needed
   • Check existing documentation structure
   • Identify project standards from CLAUDE.md
   • Context File Selection:
     • Interactive Mode (automation_mode = false): Ask user: "Do you need me to reference existing code/files for this document?"
     • Automated Mode (automation_mode = true): Auto-analyze project structure and select relevant files, log decision to auto_log.md

3. Identify Document Requirements:

   • For CLAUDE.md mandated documents (PROJECTWIKI.md, CHANGELOG.md, ADRs):
     • Apply standards from references/doc_templates/README.md (on-demand template loading)
     • Follow CLAUDE.md Project Knowledge Base Content Structure and Generation Rules Unified Template
   • For other documents:
     • Determine appropriate structure
     • Identify key sections needed

Phase 2: Outline Generation (Gemini CLI Session)

Invoke Gemini CLI Session via mcp__zen__clink:

Tool: mcp__zen__clink
Parameters:
- cli_name: "gemini"  # Launches 'gemini' command in WSL
- prompt: "Generate a detailed outline for [document type] covering [scope].
          Context: [provide all gathered context]
          Requirements: [standards from CLAUDE.md if applicable]
          Purpose: [document purpose]
          Audience: [target readers]"
- files: [list of relevant file paths for context - absolute paths]
- role: "default" (or "planner" for complex planning tasks)
- continuation_id: [if continuing from previous gemini CLI session]

What Happens:

1. zen-mcp clink opens a gemini CLI session in WSL
2. The prompt and files are passed into the gemini CLI environment
3. All outline generation work is executed inside the gemini CLI session
4. The gemini CLI session returns the completed outline
5. The session context is preserved via continuation_id for future calls

Gemini CLI Session Output: Detailed outline with:

• Main sections and subsections
• Key points to cover in each section
• Special considerations (diagrams, code examples, etc.)

Phase 3: Outline Review & Approval (Main Claude + User)

Main Claude's Responsibility:

** automation_mode check**: [AUTOMATION_MODE: false] → Interactive / true → Automated

Interactive Mode (automation_mode=false, Default)

1. Present Outline to User:

   Gemini CLI has generated document outline:
   
   [Show outline]
   
   Do you approve this outline?
   - Yes: Continue writing
   - No: Please provide modification suggestions
   - Modify: [Specific modification suggestions]

2. Wait for User Approval - Do NOT proceed without confirmation

3. Iterate if Needed: If user requests changes, provide feedback to gemini and regenerate outline

Automated Mode (automation_mode=true)

1. Main Claude Reviews Outline Autonomously (based on automation_mode=true):

   • Check completeness: All required sections present?
   • Check structure: Follows template requirements?
   • Check scope: Covers all identified needs?
   • Check standards: Aligns with CLAUDE.md?

2. Auto-Decision: Meets standards → auto-approve + log; Else → retry (max 2×) + log, escalate if failed

3. Present Decision to User (Information Only):

    Outline auto-approved (automated mode)
   
   [Show outline summary]
   
   Approval reasons:
   - Structure complete
   - Meets template requirements
   - Covers all requirements
   
   Continuing to write complete document...

Phase 4: Document Writing (Gemini CLI Session)

After Outline Approval, Invoke Gemini CLI Session:

Tool: mcp__zen__clink
Parameters:
- cli_name: "gemini"  # Reuses the same gemini CLI session in WSL
- prompt: "Write the complete [document type] based on this approved outline:
          [outline]

          Writing Guidelines:
          - Follow the outline structure exactly
          - For PROJECTWIKI.md/CHANGELOG.md/ADR: strictly follow templates in references/doc_templates/README.md (load specific templates as needed)
          - Use Mermaid diagrams where appropriate (```mermaid blocks)
          - Write in clear, professional Chinese (or English if specified)
          - Include code examples where helpful
          - Ensure consistency with CLAUDE.md standards

          Context: [all gathered context]
          Referenced files: [files to reference]"
- files: [relevant files - absolute paths]
- role: "default"
- continuation_id: [reuse from outline generation - maintains session context]

What Happens:

1. zen-mcp clink reconnects to the existing gemini CLI session using continuation_id
2. The session has context from the previous outline generation
3. The full document writing work is executed inside the gemini CLI session
4. The gemini CLI session returns the completed markdown document

Gemini CLI Session Output: Complete markdown document

Phase 5: Review & Finalization (Main Claude + User)

Main Claude's Responsibility:

** automation_mode check**: [AUTOMATION_MODE: false] → Interactive / true → Automated

Interactive Mode (automation_mode=false, Default)

1. Present Document:

   Gemini CLI has completed document writing:
   
   Document type: [type]
   File path: [proposed path]
   
   [Show document content or summary]
   
   Please review this document:
   - Approve and save
   - 🔄 Needs modification: [Please specify modification content]
   - Regenerate

2. Handle Feedback:

   • If approved: Write the document to the file system
   • If modifications needed: Provide feedback to gemini for revision
   • If regeneration needed: Return to Phase 2

3. Finalize:

   • Save document to appropriate location
   • Update CHANGELOG.md if this is a significant documentation change
   • Confirm completion with user

Automated Mode (automation_mode=true)

1. Main Claude Validates Document Autonomously (based on automation_mode=true):

   • For PROJECTWIKI/CHANGELOG/ADR: Check against references/doc_templates/README.md (load specific templates for validation)
     • All required sections present?
     • Mermaid diagrams included?
     • Links are valid?
     • Consistent with CLAUDE.md standards?
   • For other documents: Check completeness, clarity, and consistency

2. Auto-Decision: Meets quality → auto-approve + save + update CHANGELOG + log; Else → retry (max 2×) + log, escalate if failed

3. Present Final Result to User (Information Only):

    Document auto-completed and saved (automated mode)
   
   Document type: [type]
   File path: [actual path]
   
   Quality checks:
   - Structure complete
   - Meets standards
   - Format correct
   - Links valid
   
   [Show document summary or key sections]
   
   CHANGELOG.md automatically updated

Test Code Writing Workflow

Phase 1: Preparation & Context Gathering (Main Claude)

Main Claude's Responsibility:

1. Understand Testing Need:

   • What code/module needs testing?
   • Test type: unit, integration, or E2E?
   • Testing framework: pytest, unittest, jest, etc.?
   • Coverage requirements: Read from context [COVERAGE_TARGET: X%] (default 85% if missing)

2. Gather Context:

   • Read the code to be tested
   • Identify key functions/classes/modules
   • Check existing test structure
   • Review testing standards from CLAUDE.md

3. Identify Test Requirements:

   • Key functionality to test
   • Edge cases and boundary conditions
   • Error handling scenarios
   • Performance considerations if applicable

Phase 2: Test Code Generation (Gemini CLI Session)

Invoke Gemini CLI Session via mcp__zen__clink:

Tool: mcp__zen__clink
Parameters:
- cli_name: "gemini"  # Launches 'gemini' command in WSL
- prompt: "Generate comprehensive test code for [module/function].

          Code to Test:
          [code content or file references]

          Test Requirements:
          - Framework: [pytest/unittest/etc.]
          - Test types: [unit/integration/E2E]
          - Coverage target: ≥ {coverage_target from context, e.g., 85%}
          - Include: normal cases, edge cases, error handling, boundary conditions

          Standards:
          - Follow best practices from references/test_patterns.md
          - Clear test names and assertions
          - Proper setup/teardown
          - Mock external dependencies
          - Document complex test logic

          Context: [project structure, existing tests, conventions]"
- files: [code files to test + existing test examples - absolute paths]
- role: "default"
- continuation_id: [if continuing from previous gemini CLI session]

What Happens:

1. zen-mcp clink opens a gemini CLI session in WSL
2. Source code and test examples are passed into the gemini CLI environment
3. All test code generation work is executed inside the gemini CLI session
4. The gemini CLI session returns the completed test code file(s)

Gemini CLI Session Output: Complete test code file(s)

Phase 3: Test Code Validation (Codex)

Main Claude invokes Codex via mcp__zen__codereview:

Tool: mcp__zen__codereview
Parameters:
- step: "Review the test code generated by gemini for quality, completeness, and adherence to testing standards.

        Focus Areas:
        - Test coverage adequacy
        - Assertion completeness
        - Edge case handling
        - Code quality (readability, maintainability)
        - Framework best practices
        - Mock/fixture usage
        - Error handling in tests"
- step_number: 1
- total_steps: 2-3
- next_step_required: true
- findings: ""
- relevant_files: [absolute paths to generated test files]
- review_type: "full"
- model: "codex"
- review_validation_type: "external"
- confidence: "exploring"
- files_checked: [test file paths]

Codex Output: Review findings with identified issues (if any)

Phase 4: Test Code Correction (If Needed - Codex CLI)

If Codex CLI Identifies Issues:

** automation_mode check**: [AUTOMATION_MODE: false] → Interactive / true → Automated

Interactive Mode (automation_mode=false, Default)

Main Claude presents findings to user:

Codex CLI check found the following issues:

[Critical] Test file A:line B - Missing boundary condition tests
[Medium] Test file A:line C - Assertions not specific enough
...

Do you approve Codex CLI auto-correcting these issues?
- Yes: Continue corrections
- No: Manual modification

After approval, codex CLI applies corrections (following codex-code-reviewer workflow).

Automated Mode (automation_mode=true)

Main Claude reviews issues and decides autonomously (based on automation_mode=true):

1. Evaluate Issue Severity:

   • Critical/High severity: Always fix
   • Medium severity: Fix if straightforward
   • Low severity: Fix if no risk

2. Auto-Decision: Fixable + low risk → auto-approve + log; Complex/high-risk → escalate + log

3. Present Decision to User (Information Only):

    Test code issues auto-corrected (automated mode)
   [automation_mode=true set by router]
   
   Corrected issues:
   - [Critical] Added boundary condition tests
   - [Medium] Enhanced assertion descriptions
   - [Low] Optimized test naming
   
   Decision basis: automation_mode=true, all issues safely fixable
   Recorded to auto_log.md
   
   Continuing to run tests...

Phase 5: Test Execution & Review (Main Claude + User)

Main Claude's Responsibility:

** automation_mode check**: [AUTOMATION_MODE: false] → Interactive / true → Automated

1. Execute Tests:
   • Run the test suite using appropriate commands
   • Capture output and results
   • Analyze failures if any

Interactive Mode (automation_mode=false, Default)

2. Present Results to User:

   Gemini CLI has completed test code writing, Codex CLI has verified quality.
   
   Test files: [file paths]
   Coverage: [percentage]
   
   Test run results:
   
    Passed: X tests
    Failed: Y tests
     Skipped: Z tests
   
   [Detailed results]
   
   Are you satisfied? Need adjustments?
   - Approve and save
   - 🔄 Needs adjustment
   - Regenerate

3. Iterate if Needed:

   • If tests fail due to test code issues: Provide feedback to gemini/codex for correction
   • If tests reveal bugs in source code: Handle separately (not this skill's responsibility)

Automated Mode (automation_mode=true)

2. Main Claude Evaluates Test Results Autonomously (based on automation_mode=true):

   • Success Criteria:
     • All tests pass (or only expected skips)
     • Coverage ≥ coverage_target (read from context via [COVERAGE_TARGET: X%], default 85%)
     • No critical failures

3. Auto-Decision: Pass + coverage ≥ target → auto-save + log; Fail → analyze: fixable → retry (max 2×), source bugs → report + save, persistent → escalate

4. Present Final Result to User (Information Only):

    Tests auto-completed (automated mode)
   
   Test files: [file paths]
   
   Test run results:
   - Passed: X tests (100%)
   - Coverage: 78%
   
   Quality checks:
   - All tests passed
   - Coverage met target (≥ coverage_target, e.g. 85%)
   - Test structure clear
   - Assertions complete
   
   Test files saved

Collaboration Guidelines