gencode-ai 0.1.0

package/docs/proposals/0003-task-subagents.md

@@ -0,0 +1,333 @@
+# Proposal: Task Tool & Subagent System
+
+- **Proposal ID**: 0003
+- **Author**: mycode team
+- **Status**: Draft
+- **Created**: 2025-01-15
+- **Updated**: 2025-01-15
+
+## Summary
+
+Implement a Task tool that launches specialized subagents to handle complex, multi-step tasks autonomously. Subagents run with separate context windows, specific tool access, and defined expertise areas, enabling efficient handling of specialized tasks without polluting the main conversation context.
+
+## Motivation
+
+Currently, mycode uses a single agent for all tasks. This leads to:
+
+1. **Context pollution**: Complex research fills up main context
+2. **No specialization**: One agent can't optimize for different task types
+3. **No parallelism**: Tasks must run sequentially
+4. **Context overflow**: Long operations exhaust context limits
+5. **No delegation**: Can't spawn workers for independent subtasks
+
+A subagent system enables parallel, specialized, context-isolated task execution.
+
+## Claude Code Reference
+
+Claude Code's Task tool launches specialized agents with defined capabilities:
+
+### Tool Definition
+```typescript
+Task({
+  description: "Explore authentication code",  // Short description (3-5 words)
+  prompt: "Find all authentication-related files...",  // Detailed task
+  subagent_type: "Explore",  // Agent specialization
+  model: "haiku",            // Optional: model selection
+  run_in_background: false   // Optional: async execution
+})
+```
+
+### Available Agent Types
+| Type | Description | Tools Available |
+|------|-------------|-----------------|
+| `Explore` | Fast codebase exploration | Read, Glob, Grep (read-only) |
+| `Plan` | Architecture and design | All read tools, no edit |
+| `Bash` | Command execution | Bash only |
+| `general-purpose` | Full capabilities | All tools |
+
+### Key Features
+- Separate context window per subagent
+- Constrained tool access per type
+- Background execution option
+- Model selection (haiku for simple, sonnet for complex)
+- Resume capability with agent ID
+- Parallel launch (multiple Task calls in one message)
+
+### Example Usage
+```
+User: Find where authentication errors are handled
+
+Agent: I'll launch an Explore agent to search the codebase.
+[Task:
+  description: "Find auth error handling"
+  prompt: "Search for authentication error handling..."
+  subagent_type: "Explore"
+]
+
+Explore Agent Result:
+Found authentication error handling in:
+- src/auth/errors.ts:45 - AuthError class
+- src/middleware/auth.ts:78 - error handler
+...
+
+Agent: Based on the exploration, authentication errors are handled in...
+```
+
+## Detailed Design
+
+### API Design
+
+```typescript
+// src/subagents/types.ts
+type SubagentType = 'Explore' | 'Plan' | 'Bash' | 'general-purpose';
+
+interface TaskInput {
+  description: string;      // Short description (3-5 words)
+  prompt: string;           // Detailed task instructions
+  subagent_type: SubagentType;
+  model?: 'haiku' | 'sonnet' | 'opus';
+  run_in_background?: boolean;
+  resume?: string;          // Agent ID to resume
+  max_turns?: number;       // Max conversation turns
+}
+
+interface TaskOutput {
+  success: boolean;
+  result?: string;
+  agentId: string;          // For resume capability
+  outputFile?: string;      // For background tasks
+  error?: string;
+}
+
+interface SubagentConfig {
+  type: SubagentType;
+  allowedTools: string[];
+  defaultModel: string;
+  systemPrompt: string;
+  maxTurns: number;
+}
+```
+
+```typescript
+// src/subagents/task-tool.ts
+const taskTool: Tool<TaskInput> = {
+  name: 'Task',
+  description: `Launch a specialized subagent for complex tasks.
+
+Available agent types:
+- Explore: Fast codebase exploration (read-only)
+- Plan: Architecture design and planning
+- Bash: Command execution specialist
+- general-purpose: Full capabilities
+
+Guidelines:
+- Use Explore for searching/understanding code
+- Use Plan for designing implementation approaches
+- Use Bash for running commands
+- Include 3-5 word description
+- Provide detailed prompt with context
+- Use haiku for simple, sonnet for complex tasks
+- Launch multiple agents in parallel when possible
+`,
+  parameters: z.object({
+    description: z.string().min(1),
+    prompt: z.string().min(1),
+    subagent_type: z.enum(['Explore', 'Plan', 'Bash', 'general-purpose']),
+    model: z.enum(['haiku', 'sonnet', 'opus']).optional(),
+    run_in_background: z.boolean().optional(),
+    resume: z.string().optional(),
+    max_turns: z.number().positive().optional()
+  }),
+  execute: async (input, context) => { ... }
+};
+```
+
+```typescript
+// src/subagents/subagent.ts
+class Subagent {
+  private id: string;
+  private type: SubagentType;
+  private config: SubagentConfig;
+  private agent: Agent;
+
+  constructor(type: SubagentType, config?: Partial<SubagentConfig>);
+
+  // Execute task and return result
+  async run(prompt: string): Promise<TaskOutput>;
+
+  // Run in background, return immediately
+  async runInBackground(prompt: string): Promise<{ agentId: string; outputFile: string }>;
+
+  // Resume from previous execution
+  async resume(agentId: string): Promise<TaskOutput>;
+
+  // Get current status
+  getStatus(): 'running' | 'completed' | 'error';
+}
+```
+
+### Implementation Approach
+
+1. **Subagent Registry**: Define configs for each agent type
+2. **Tool Filtering**: Restrict tools based on agent type
+3. **Context Isolation**: Each subagent gets fresh context
+4. **Result Aggregation**: Collect and format subagent results
+5. **Background Execution**: Spawn async workers with output files
+6. **Resume System**: Store agent state for continuation
+
+```typescript
+// Subagent configurations
+const SUBAGENT_CONFIGS: Record<SubagentType, SubagentConfig> = {
+  'Explore': {
+    type: 'Explore',
+    allowedTools: ['Read', 'Glob', 'Grep', 'LS'],
+    defaultModel: 'haiku',
+    systemPrompt: 'You are a codebase exploration specialist...',
+    maxTurns: 10
+  },
+  'Plan': {
+    type: 'Plan',
+    allowedTools: ['Read', 'Glob', 'Grep', 'LS', 'WebFetch'],
+    defaultModel: 'sonnet',
+    systemPrompt: 'You are a software architect designing solutions...',
+    maxTurns: 5
+  },
+  'Bash': {
+    type: 'Bash',
+    allowedTools: ['Bash', 'KillShell'],
+    defaultModel: 'haiku',
+    systemPrompt: 'You are a shell command specialist...',
+    maxTurns: 20
+  },
+  'general-purpose': {
+    type: 'general-purpose',
+    allowedTools: ['*'],  // All tools
+    defaultModel: 'sonnet',
+    systemPrompt: 'You are a general-purpose coding assistant...',
+    maxTurns: 20
+  }
+};
+```
+
+### File Changes
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/subagents/types.ts` | Create | Subagent type definitions |
+| `src/subagents/task-tool.ts` | Create | Task tool implementation |
+| `src/subagents/subagent.ts` | Create | Subagent class |
+| `src/subagents/configs.ts` | Create | Subagent configurations |
+| `src/subagents/background-runner.ts` | Create | Background execution |
+| `src/subagents/index.ts` | Create | Module exports |
+| `src/tools/index.ts` | Modify | Register Task tool |
+| `src/agent/agent.ts` | Modify | Support tool filtering |
+
+## User Experience
+
+### Subagent Launch Display
+```
+Agent: I'll explore the codebase to understand the authentication system.
+
+┌─ Launching Subagent ──────────────────────────┐
+│ Type: Explore                                 │
+│ Task: Find auth error handling                │
+│ Model: haiku                                  │
+└───────────────────────────────────────────────┘
+
+[Explore agent working...]
+
+┌─ Subagent Result ─────────────────────────────┐
+│ Found 3 relevant files:                       │
+│ • src/auth/errors.ts (AuthError class)        │
+│ • src/middleware/auth.ts (error handler)      │
+│ • src/utils/auth-helpers.ts (validation)      │
+└───────────────────────────────────────────────┘
+```
+
+### Parallel Execution
+```
+Agent: I'll search for both authentication and authorization code.
+[Launching 2 Explore agents in parallel...]
+
+┌─ Agent 1: Auth ───────────────────────────────┐
+│ Status: Completed                             │
+│ Found: 5 files                                │
+└───────────────────────────────────────────────┘
+
+┌─ Agent 2: Authorization ──────────────────────┐
+│ Status: Completed                             │
+│ Found: 3 files                                │
+└───────────────────────────────────────────────┘
+```
+
+### Background Task
+```
+Agent: I'll start a long-running analysis in the background.
+[Task running in background: agent-abc123]
+
+You can continue working. Use /task-status abc123 to check progress.
+```
+
+## Alternatives Considered
+
+### Alternative 1: Single Agent with Mode Switching
+Switch modes instead of spawning agents.
+
+**Pros**: Simpler, shared context
+**Cons**: Context pollution, no parallelism
+**Decision**: Rejected - Context isolation is key benefit
+
+### Alternative 2: Process-Based Workers
+Spawn actual OS processes.
+
+**Pros**: True isolation, crash protection
+**Cons**: Overhead, complexity, IPC
+**Decision**: Rejected for initial implementation
+
+### Alternative 3: Fixed Agent Types Only
+No custom agent configurations.
+
+**Pros**: Simpler
+**Cons**: Less flexibility
+**Decision**: Rejected - Custom agents enable future extensibility
+
+## Security Considerations
+
+1. **Tool Restrictions**: Strictly enforce tool allowlists
+2. **Resource Limits**: Limit max turns and execution time
+3. **Output Isolation**: Subagent can't access main context
+4. **Permission Inheritance**: Subagents respect main permission settings
+5. **Background Cleanup**: Clean up stale background tasks
+
+## Testing Strategy
+
+1. **Unit Tests**:
+   - Tool filtering logic
+   - Config validation
+   - Result formatting
+
+2. **Integration Tests**:
+   - Subagent lifecycle
+   - Background execution
+   - Resume functionality
+
+3. **Manual Testing**:
+   - Various agent types
+   - Parallel execution
+   - Complex multi-step tasks
+
+## Migration Path
+
+1. **Phase 1**: Core Explore and Plan agents
+2. **Phase 2**: Bash agent and background execution
+3. **Phase 3**: Resume capability
+4. **Phase 4**: Custom agent definitions
+5. **Phase 5**: Parallel execution optimization
+
+No breaking changes to existing functionality.
+
+## References
+
+- [Claude Code Task Tool Documentation](https://code.claude.com/docs/en/tools)
+- [Claude Code Subagent System](https://github.com/Piebald-AI/claude-code-system-prompts)
+- [Understanding Claude Code Full Stack](https://alexop.dev/posts/understanding-claude-code-full-stack/)

package/docs/proposals/0004-plan-mode.md

@@ -0,0 +1,338 @@
+# Proposal: Plan Mode
+
+- **Proposal ID**: 0004
+- **Author**: mycode team
+- **Status**: Draft
+- **Created**: 2025-01-15
+- **Updated**: 2025-01-15
+
+## Summary
+
+Implement a Plan Mode that enables the agent to thoroughly explore and design implementation approaches before writing code. In plan mode, the agent can only read and explore (no edits), creates a structured plan file, and requires user approval before proceeding with implementation.
+
+## Motivation
+
+Currently, mycode jumps directly into implementation. This leads to:
+
+1. **Wasted effort**: Implementing wrong approach requires redoing work
+2. **Misalignment**: Agent's assumptions may not match user intent
+3. **Poor architecture**: No time for design consideration
+4. **Unexpected changes**: Users surprised by what gets modified
+5. **No preview**: Can't review approach before execution
+
+Plan mode enables careful design and user approval before changes.
+
+## Claude Code Reference
+
+Claude Code's Plan Mode provides structured planning workflow:
+
+### Activation
+```
+User: /plan  (or use EnterPlanMode tool)
+```
+
+### Key Features
+- Agent restricted to read-only tools (no Edit, Write, Bash writes)
+- Structured plan written to plan file
+- 5-phase workflow: Understanding → Design → Review → Final Plan → Exit
+- User questions via AskUserQuestion tool
+- Plan approval via ExitPlanMode tool
+- Permission pre-requests for implementation
+
+### Plan Mode Phases
+1. **Initial Understanding**: Explore codebase, understand request
+2. **Design**: Create implementation approach
+3. **Review**: Verify alignment with user intent
+4. **Final Plan**: Write concise plan to file
+5. **Exit**: Call ExitPlanMode for approval
+
+### Example Usage
+```
+User: /plan Add user authentication to the app
+
+Agent: [Enters plan mode]
+I'll explore the codebase to understand the current structure.
+[Read, Glob, Grep - exploration]
+
+Based on my exploration, I have a question:
+[AskUserQuestion: Which auth method? OAuth/JWT/Session]
+
+User: JWT
+
+Agent: [Writes plan to .claude/plans/xxx.md]
+
+## Authentication Implementation Plan
+
+### Approach
+- Add JWT-based authentication
+- Create auth middleware
+- Add login/logout endpoints
+
+### Files to Modify
+- src/middleware/auth.ts (create)
+- src/routes/auth.ts (create)
+- src/models/user.ts (modify)
+
+### Verification
+- Run test suite
+- Manual login/logout test
+
+[ExitPlanMode]
+
+User: [Reviews and approves plan]
+
+Agent: [Exits plan mode, begins implementation]
+```
+
+## Detailed Design
+
+### API Design
+
+```typescript
+// src/planning/types.ts
+interface PlanModeState {
+  active: boolean;
+  planFile: string;
+  phase: 'understanding' | 'design' | 'review' | 'final' | 'approval';
+  explorationResults: ExplorationResult[];
+  userAnswers: Record<string, string>;
+}
+
+interface PlanFile {
+  id: string;
+  title: string;
+  createdAt: Date;
+  approach: string;
+  files: FileChange[];
+  verification: string[];
+  permissions: PermissionRequest[];
+}
+
+interface FileChange {
+  path: string;
+  action: 'create' | 'modify' | 'delete';
+  description: string;
+}
+
+interface PermissionRequest {
+  tool: 'Bash';
+  prompt: string;  // e.g., "run tests", "install dependencies"
+}
+```
+
+```typescript
+// src/planning/enter-plan-mode-tool.ts
+const enterPlanModeTool: Tool<{}> = {
+  name: 'EnterPlanMode',
+  description: `Enter plan mode for non-trivial implementation tasks.
+
+Use plan mode when:
+- New feature implementation
+- Multiple valid approaches exist
+- Code modifications affect existing behavior
+- Architectural decisions required
+- Multi-file changes expected
+- Requirements are unclear
+
+Skip plan mode for:
+- Single-line fixes
+- Trivial changes
+- Specific, detailed instructions given
+`,
+  parameters: z.object({}),
+  execute: async (input, context) => { ... }
+};
+```
+
+```typescript
+// src/planning/exit-plan-mode-tool.ts
+const exitPlanModeTool: Tool<ExitPlanModeInput> = {
+  name: 'ExitPlanMode',
+  description: `Exit plan mode and request user approval.
+
+Call this when:
+- Plan is complete and written to plan file
+- Ready for user to review and approve
+
+Include allowedPrompts to request permissions needed for implementation.
+`,
+  parameters: z.object({
+    allowedPrompts: z.array(z.object({
+      tool: z.literal('Bash'),
+      prompt: z.string()
+    })).optional()
+  }),
+  execute: async (input, context) => { ... }
+};
+```
+
+### Implementation Approach
+
+1. **Mode Management**: Track plan mode state in session
+2. **Tool Filtering**: In plan mode, only allow read tools + plan file write
+3. **Plan File**: Create structured plan at `.mycode/plans/<id>.md`
+4. **Phase Tracking**: Guide agent through planning phases
+5. **Approval Flow**: Present plan for user approval
+6. **Permission Pre-auth**: Allow requesting bash permissions upfront
+
+```typescript
+// Plan mode tool filtering
+const PLAN_MODE_ALLOWED_TOOLS = [
+  'Read',
+  'Glob',
+  'Grep',
+  'LS',
+  'WebFetch',
+  'WebSearch',
+  'Task',           // For Explore/Plan subagents
+  'AskUserQuestion',
+  'TodoWrite',
+  'EnterPlanMode',
+  'ExitPlanMode',
+  'Write'           // Only for plan file
+];
+
+function filterToolsForPlanMode(tools: Tool[], planFile: string): Tool[] {
+  return tools.filter(tool => {
+    if (PLAN_MODE_ALLOWED_TOOLS.includes(tool.name)) {
+      if (tool.name === 'Write') {
+        // Only allow writing to plan file
+        return (input) => input.file_path === planFile;
+      }
+      return true;
+    }
+    return false;
+  });
+}
+```
+
+### File Changes
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/planning/types.ts` | Create | Plan mode type definitions |
+| `src/planning/plan-manager.ts` | Create | Plan mode state management |
+| `src/planning/enter-plan-mode-tool.ts` | Create | EnterPlanMode tool |
+| `src/planning/exit-plan-mode-tool.ts` | Create | ExitPlanMode tool |
+| `src/planning/plan-file.ts` | Create | Plan file read/write |
+| `src/planning/index.ts` | Create | Module exports |
+| `src/agent/agent.ts` | Modify | Plan mode integration |
+| `src/tools/index.ts` | Modify | Register plan tools |
+
+## User Experience
+
+### Entering Plan Mode
+```
+User: Help me implement user authentication
+
+Agent: This is a non-trivial task. I'll enter plan mode to design the approach.
+
+┌─ Plan Mode Active ────────────────────────────┐
+│ Read-only exploration enabled                 │
+│ Plan file: .mycode/plans/auth-impl.md         │
+│                                               │
+│ Phase 1/5: Understanding                      │
+└───────────────────────────────────────────────┘
+
+Let me explore the current codebase structure...
+```
+
+### Plan Display
+```
+┌─ Implementation Plan ─────────────────────────┐
+│                                               │
+│ ## JWT Authentication                         │
+│                                               │
+│ ### Approach                                  │
+│ - Add JWT token generation and validation    │
+│ - Create auth middleware for protected routes│
+│ - Add user registration and login endpoints  │
+│                                               │
+│ ### Files to Change                           │
+│ + src/middleware/auth.ts (create)            │
+│ + src/routes/auth.ts (create)                │
+│ ~ src/models/user.ts (modify)                │
+│ ~ src/app.ts (modify)                        │
+│                                               │
+│ ### Verification                              │
+│ - npm test                                    │
+│ - Manual login flow test                     │
+│                                               │
+└───────────────────────────────────────────────┘
+
+Ready to proceed? [Approve] [Modify] [Cancel]
+```
+
+### Plan Approval
+```
+User: [Approves plan]
+
+Agent: Plan approved. Exiting plan mode and beginning implementation.
+
+┌─ Implementation Started ──────────────────────┐
+│ Following plan: .mycode/plans/auth-impl.md    │
+│ Pre-approved: npm test, npm install           │
+└───────────────────────────────────────────────┘
+```
+
+## Alternatives Considered
+
+### Alternative 1: Inline Planning
+Plan in regular output without special mode.
+
+**Pros**: Simpler
+**Cons**: No enforcement, easy to skip, no approval gate
+**Decision**: Rejected - Mode provides structure and safety
+
+### Alternative 2: Mandatory Planning
+Always require plan mode for changes.
+
+**Pros**: Maximum safety
+**Cons**: Overhead for simple tasks
+**Decision**: Rejected - Optional with agent judgment is better
+
+### Alternative 3: External Plan Files
+Store plans outside project.
+
+**Pros**: No project pollution
+**Cons**: Harder to track, no version control
+**Decision**: Rejected - Project plans are versioned with project
+
+## Security Considerations
+
+1. **Tool Restrictions**: Strictly enforce read-only in plan mode
+2. **Plan File Location**: Only allow writing to designated plan directory
+3. **Permission Scope**: Pre-approved permissions are scoped and temporary
+4. **Plan Review**: User must explicitly approve before implementation
+
+## Testing Strategy
+
+1. **Unit Tests**:
+   - Mode state management
+   - Tool filtering
+   - Plan file formatting
+
+2. **Integration Tests**:
+   - Enter/exit flow
+   - Tool restriction enforcement
+   - Approval workflow
+
+3. **Manual Testing**:
+   - Various planning scenarios
+   - Phase transitions
+   - Plan file quality
+
+## Migration Path
+
+1. **Phase 1**: Basic plan mode with tool restrictions
+2. **Phase 2**: Plan file structure and writing
+3. **Phase 3**: User approval flow
+4. **Phase 4**: Permission pre-authorization
+5. **Phase 5**: Phase guidance and agent prompting
+
+No breaking changes to existing functionality.
+
+## References
+
+- [Claude Code Plan Mode Documentation](https://code.claude.com/docs/en/planning)
+- [Claude Code Best Practices - Explore, Plan, Code](https://www.anthropic.com/engineering/claude-code-best-practices)