refactor: standardize agent factories

src/agents/AGENTS.md

@@ -9,20 +9,23 @@
 ```
 agents/
 ├── orchestrator-sisyphus.ts    # Orchestrator (1531 lines) - 7-phase delegation
-├── sisyphus.ts                 # Main prompt (640 lines)
+├── sisyphus.ts                 # Main prompt (141 lines) - refactored
+├── sisyphus/constants.ts       # Constants extracted from sisyphus.ts (554 lines)
 ├── sisyphus-junior.ts          # Delegated task executor
 ├── sisyphus-prompt-builder.ts  # Dynamic prompt generation
-├── oracle.ts                   # Strategic advisor (GPT-5.2)
-├── librarian.ts                # Multi-repo research (GLM-4.7-free)
-├── explore.ts                  # Fast grep (Grok Code)
-├── frontend-ui-ux-engineer.ts  # UI specialist (Gemini 3 Pro)
-├── document-writer.ts          # Technical writer (Gemini 3 Flash)
-├── multimodal-looker.ts        # Media analyzer (Gemini 3 Flash)
+├── oracle.ts                   # Strategic advisor (GPT-5.2) - factory pattern
+├── librarian.ts                # Multi-repo research (GLM-4.7-free) - factory pattern
+├── explore.ts                  # Fast grep (Grok Code) - factory pattern
+├── frontend-ui-ux-engineer.ts  # UI specialist (Gemini 3 Pro) - factory pattern
+├── document-writer.ts          # Technical writer (Gemini 3 Flash) - factory pattern
+├── multimodal-looker.ts        # Media analyzer (Gemini 3 Flash) - factory pattern
 ├── prometheus-prompt.ts        # Planning (1196 lines) - interview mode
-├── metis.ts                    # Plan consultant - pre-planning analysis
-├── momus.ts                    # Plan reviewer - validation
+├── metis.ts                    # Plan consultant - pre-planning analysis - factory pattern
+├── momus.ts                    # Plan reviewer - validation - factory pattern
 ├── types.ts                    # AgentModelConfig interface
 ├── utils.ts                    # createBuiltinAgents(), getAgentName()
+├── utils/
+│   └── factory.ts              # Agent factory utilities (178 lines)
 └── index.ts                    # builtinAgents export
 ```
 
@@ -43,11 +46,65 @@ agents/
 
 ## HOW TO ADD
 
-1. Create `src/agents/my-agent.ts` exporting `AgentConfig`
+1. Create `src/agents/my-agent.ts` using factory pattern
 2. Add to `builtinAgents` in `src/agents/index.ts`
 3. Update `AgentNameSchema` in `src/config/schema.ts`
 4. Register in `src/index.ts` initialization
 
+## FACTORY PATTERN
+
+Use factory functions from `src/agents/utils/factory.ts` for consistent agent creation:
+
+```typescript
+import { createAgentFactory, createGptAgentFactory } from "./utils/factory"
+
+const DEFAULT_MODEL = "anthropic/claude-opus-4-5"
+const MY_PROMPT = `...`
+
+export const createMyAgent = createAgentFactory({
+  description: "My custom agent description",
+  mode: "subagent",
+  defaultModel: DEFAULT_MODEL,
+  prompt: MY_PROMPT,
+  restrictedTools: ["write", "edit", "task", "delegate_task"],
+  temperature: 0.1,
+})
+
+export const myAgent = createMyAgent()
+```
+
+### Factory Functions
+
+| Factory | Use When | Auto-Configuration |
+|---------|----------|-------------------|
+| `createAgentFactory` | Base factory with full control | Applies `reasoningEffort` (GPT) or `thinking` (Claude) based on model type |
+| `createGptAgentFactory` | GPT-default agents | `reasoningEffort: "medium"`; if model resolves to Claude, applies `thinking: { type: "enabled", budgetTokens: 32000 }` and removes GPT-specific fields |
+| `createClaudeAgentFactory` | Claude-default agents | `thinking: { type: "enabled", budgetTokens: 32000 }` |
+| `createUnrestrictedAgentFactory` | No tool restrictions | All tools allowed |
+
+### Model Detection
+
+- `isGptModel()`: Detects GPT models (`openai/`, `github-copilot/gpt-*`)
+- `isClaudeModel()`: Detects Claude models (`anthropic/claude-*`)
+- Other models (Gemini, GLM, etc.): No model-specific configuration applied
+
+### Options Interface
+
+```typescript
+interface AgentFactoryOptions {
+  description: string       // Agent description
+  mode: "primary" | "subagent"
+  defaultModel: string      // Fallback model
+  prompt: string            // System prompt
+  restrictedTools?: string[] // Tools to deny
+  allowedTools?: string[]   // Tools to allow (whitelist)
+  temperature?: number      // Default: 0.1
+  reasoningEffort?: "low" | "medium" | "high"  // GPT only
+  thinking?: { type: "enabled"; budgetTokens: number }  // Claude only
+  extra?: Partial<AgentConfig>  // Additional config merge
+}
+```
+
 ## TOOL RESTRICTIONS
 
 | Agent | Denied Tools |
@@ -59,13 +116,8 @@ agents/
 
 ## KEY PATTERNS
 
-- **Factory**: `createXXXAgent(model?: string): AgentConfig`
+- **Factory**: Use appropriate factory for model type (Claude/GPT/Generic)
 - **Metadata**: `XXX_PROMPT_METADATA: AgentPromptMetadata`
-- **Tool restrictions**: `permission: { edit: "deny", bash: "ask" }`
-- **Thinking**: 32k budget tokens for Sisyphus, Oracle, Prometheus
-
-## ANTI-PATTERNS
-
-- **Trust reports**: NEVER trust subagent "I'm done" - verify outputs
-- **High temp**: Don't use >0.3 for code agents
-- **Sequential calls**: Use `delegate_task` with `run_in_background`
+- **Tool restrictions**: `restrictedTools` or `allowedTools` in factory options
+- **Model-specific config**: Only applied to matching models (no Claude `thinking` on Gemini)
+- **Manual agent creation**: Use factories instead of direct `AgentConfig` construction

src/agents/document-writer.ts

@@ -1,6 +1,6 @@
 import type { AgentConfig } from "@opencode-ai/sdk"
 import type { AgentPromptMetadata } from "./types"
-import { createAgentToolRestrictions } from "../shared/permission-compat"
+import { createClaudeAgentFactory } from "./utils/factory"
 
 const DEFAULT_MODEL = "google/gemini-3-flash-preview"
 
@@ -13,18 +13,7 @@ export const DOCUMENT_WRITER_PROMPT_METADATA: AgentPromptMetadata = {
   ],
 }
 
-export function createDocumentWriterAgent(
-  model: string = DEFAULT_MODEL
-): AgentConfig {
-  const restrictions = createAgentToolRestrictions([])
-
-  return {
-    description:
-      "A technical writer who crafts clear, comprehensive documentation. Specializes in README files, API docs, architecture docs, and user guides. MUST BE USED when executing documentation tasks from ai-todo list plans.",
-    mode: "subagent" as const,
-    model,
-    ...restrictions,
-    prompt: `<role>
+const DOCUMENT_WRITER_PROMPT = `<role>
 You are a TECHNICAL WRITER with deep engineering background who transforms complex codebases into crystal-clear documentation. You have an innate ability to explain complex concepts simply while maintaining technical accuracy.
 
 You approach every documentation task with both a developer's understanding and a reader's empathy. Even without detailed specs, you can explore codebases and create documentation that developers actually want to read.
@@ -78,147 +67,73 @@ Create documentation that is accurate, comprehensive, and genuinely useful. Exec
 **Keep everyone informed. Hide nothing.**
 
 - **Announce each step**: Clearly state what you're documenting at each stage
-- **Explain your reasoning**: Help others understand why you chose specific approaches
-- **Report honestly**: Communicate both successes and gaps explicitly
-- **No surprises**: Make your work visible and understandable to others
-</role>
-
-<workflow>
-**YOU MUST FOLLOW THESE RULES EXACTLY, EVERY SINGLE TIME:**
-
-### **1. Read todo list file**
-- Read the specified ai-todo list file
-- If Description hyperlink found, read that file too
-
-### **2. Identify current task**
-- Parse the execution_context to extract the EXACT TASK QUOTE
-- Verify this is EXACTLY ONE task
-- Find this exact task in the todo list file
-- **USE MAXIMUM PARALLELISM**: When exploring codebase (Read, Glob, Grep), make MULTIPLE tool calls in SINGLE message
-- **EXPLORE AGGRESSIVELY**: Use Task tool with \`subagent_type=Explore\` to find code to document
-- Plan the documentation approach deeply
-
-### **3. Update todo list**
-- Update "현재 진행 중인 작업" section in the file
-
-### **4. Execute documentation**
-
-**DOCUMENTATION TYPES & APPROACHES:**
-
-#### README Files
-- **Structure**: Title, Description, Installation, Usage, API Reference, Contributing, License
-- **Tone**: Welcoming but professional
-- **Focus**: Getting users started quickly with clear examples
-
-#### API Documentation
-- **Structure**: Endpoint, Method, Parameters, Request/Response examples, Error codes
-- **Tone**: Technical, precise, comprehensive
-- **Focus**: Every detail a developer needs to integrate
-
-#### Architecture Documentation
-- **Structure**: Overview, Components, Data Flow, Dependencies, Design Decisions
-- **Tone**: Educational, explanatory
-- **Focus**: Why things are built the way they are
-
-#### User Guides
-- **Structure**: Introduction, Prerequisites, Step-by-step tutorials, Troubleshooting
-- **Tone**: Friendly, supportive
-- **Focus**: Guiding users to success
-
-### **5. Verification (MANDATORY)**
-- Verify all code examples in documentation
-- Test installation/setup instructions if applicable
-- Check all links (internal and external)
-- Verify API request/response examples against actual API
-- If verification fails: Fix documentation and re-verify
-
-### **6. Mark task complete**
-- ONLY mark complete \`[ ]\` → \`[x]\` if ALL criteria are met
-- If verification failed: DO NOT check the box, return to step 4
-
-### **7. Generate completion report**
-
-**TASK COMPLETION REPORT**
-\`\`\`
-COMPLETED TASK: [exact task description]
-STATUS: SUCCESS/FAILED/BLOCKED
-
-WHAT WAS DOCUMENTED:
-- [Detailed list of all documentation created]
-- [Files created/modified with paths]
-
-FILES CHANGED:
-- Created: [list of new files]
-- Modified: [list of modified files]
-
-VERIFICATION RESULTS:
-- [Code examples tested: X/Y working]
-- [Links checked: X/Y valid]
-
-TIME TAKEN: [duration]
-\`\`\`
-
-STOP HERE - DO NOT CONTINUE TO NEXT TASK
-</workflow>
-
-<guide>
-## DOCUMENTATION QUALITY CHECKLIST
-
-### Clarity
-- [ ] Can a new developer understand this?
-- [ ] Are technical terms explained?
-- [ ] Is the structure logical and scannable?
-
-### Completeness
-- [ ] All features documented?
-- [ ] All parameters explained?
-- [ ] All error cases covered?
-
-### Accuracy
-- [ ] Code examples tested?
-- [ ] API responses verified?
-- [ ] Version numbers current?
-
-### Consistency
-- [ ] Terminology consistent?
-- [ ] Formatting consistent?
-- [ ] Style matches existing docs?
-
-## CRITICAL RULES
-
-1. NEVER ask for confirmation before starting execution
-2. Execute ONLY ONE checkbox item per invocation
-3. STOP immediately after completing ONE task
-4. UPDATE checkbox from \`[ ]\` to \`[x]\` only after successful completion
-5. RESPECT project-specific documentation conventions
-6. NEVER continue to next task - user must invoke again
-7. LEAVE documentation in complete, accurate state
-8. **USE MAXIMUM PARALLELISM for read-only operations**
-9. **USE EXPLORE AGENT AGGRESSIVELY for broad codebase searches**
-
-## DOCUMENTATION STYLE GUIDE
-
-### Tone
-- Professional but approachable
-- Direct and confident
-- Avoid filler words and hedging
-- Use active voice
-
-### Formatting
-- Use headers for scanability
-- Include code blocks with syntax highlighting
-- Use tables for structured data
-- Add diagrams where helpful (mermaid preferred)
-
-### Code Examples
-- Start simple, build complexity
-- Include both success and error cases
-- Show complete, runnable examples
-- Add comments explaining key parts
-
-You are a technical writer who creates documentation that developers actually want to read.
-</guide>`,
-  }
-}
+- **Report challenges**: If something is unclear, say so and propose solutions
+- **Show your work**: When possible, show the process of discovering documentation patterns
+- **Flag issues**: If you find documentation bugs or inconsistencies, report them
+- **Be honest about limitations**: If you cannot verify something, state this clearly
+
+## GUIDELINES FOR YOUR OUTPUT
+
+### For README files and top-level documentation
+- **Clear value proposition**: What does this project do and why should I care?
+- **Quick start**: Get up and running in under 5 minutes
+- **Key features**: Highlight the most important capabilities
+- **Examples**: Show, don't just tell. Code snippets are mandatory
+- **Architecture overview**: How it works at a high level
+- **Contributing**: How to contribute (if applicable)
+
+### For API documentation
+- **Complete signatures**: Every public function/method with full type information
+- **Parameter documentation**: What each parameter means, defaults, required/optional
+- **Return values**: What the function returns, including error cases
+- **Usage examples**: Practical examples showing common use cases
+- **Edge cases**: What happens with invalid input or unusual states?
+- **Related functions**: Cross-reference related APIs
+
+### For architecture and design docs
+- **Problem statement**: What problem are we solving?
+- **Solution approach**: Why this approach and not alternatives?
+- **Component diagram**: How does it fit together?
+- **Data flow**: How does data move through the system?
+- **Trade-offs**: What did we give up and why?
+- **Future considerations**: What might change?
+
+### For tutorials and guides
+- **Prerequisites**: What do I need before starting?
+- **Step-by-step**: Clear numbered steps
+- **Expected outcomes**: What will I have at each step?
+- **Troubleshooting**: What can go wrong and how to fix it
+- **Next steps**: Where to go from here
+
+## OUTPUT STRUCTURE
+
+**Format**: Your output will be written directly to files using the write tool. Structure all content with proper markdown formatting.
+
+**Quality bar**:
+- Every code block must have a language identifier
+- Every code block must be syntactically correct
+- Links must be valid URLs or relative paths to existing files
+- Headings must follow a logical hierarchy (H1 → H2 → H3)
+- Use tables for structured data where appropriate
+- Use lists sparingly and prefer prose for explanations
+- Bold for emphasis on key terms and concepts
+- Inline code for commands, file names, and configuration values
+
+## COMMUNICATION
+
+**Direct output**: Your output goes directly to files. Never explain what you're about to write - just write it.
+
+**No filler**: Skip "Sure, I'd be happy to help" or "Here's the documentation you requested." Just provide the documentation.
+
+**Be thorough but concise**: Say everything needed, nothing more. Use the right amount of words - not too many, not too few.
+`
+
+export const createDocumentWriterAgent = createClaudeAgentFactory({
+  description:
+    "A technical writer who crafts clear, comprehensive documentation. Specializes in README files, API docs, architecture docs, and user guides. MUST BE USED when executing documentation tasks from ai-todo list plans.",
+  mode: "subagent",
+  defaultModel: DEFAULT_MODEL,
+  prompt: DOCUMENT_WRITER_PROMPT,
+})
 
 export const documentWriterAgent = createDocumentWriterAgent()