Implement qstudio plan command #51

New Issue

2026-01-03T23:46:24Z

KofTwentyTwo commented

2026-01-03 23:46:24 +00:00

(Migrated from github.com)

User Story

As a developer, I want to generate implementation plans using AI so I can get structured guidance on how to implement features in my QQQ project.

Design

Command Interface

# Generate plan from prompt
qstudio plan "Add a new Order entity with CRUD operations"

# Generate plan from file
qstudio plan --file requirements.md

# Specify output location
qstudio plan "Add authentication" --output docs/PLAN-auth.md

# Use specific LLM provider
qstudio plan "Add caching" --provider anthropic

# Dry run (show what would be sent to LLM)
qstudio plan "Add logging" --dry-run

# Estimate tokens/cost
qstudio plan "Add metrics" --estimate

Output Format (plan.md)

# Implementation Plan: Add Order Entity

## Overview
Create a new Order entity with full CRUD operations following QQQ patterns.

## Files to Create
| File | Purpose |
|------|---------|
| `src/.../model/Order.java` | RecordEntity for orders |
| `src/.../metadata/OrderTableMetaDataProducer.java` | Table metadata |
| `src/.../api/OrderApiMetaDataProducer.java` | API endpoints |

## Implementation Steps

### Step 1: Create Order Entity
Create `Order.java` extending QRecord with fields:
- id (Integer, primary key)
- customerId (Integer, foreign key)
- orderDate (LocalDate)
- status (String)

### Step 2: Create Table Metadata
...

## Estimated Effort
- Files: 4
- Lines of code: ~200
- Complexity: Low

## Generated
- Date: 2024-01-15T10:30:00Z
- Provider: anthropic/claude-3-opus
- Tokens: 2,450

LLM Provider Configuration

# ~/.qctl/qctl.yaml
qstudio:
  default_provider: anthropic
  providers:
    anthropic:
      model: claude-3-opus-20240229
      api_key: ${ANTHROPIC_API_KEY}
    openai:
      model: gpt-4-turbo
      api_key: ${OPENAI_API_KEY}
    local:
      endpoint: http://localhost:11434
      model: codellama:34b

Files to Create/Modify

File	Action	Purpose
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/PlanCommand.java`	Create	Main plan command
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/llm/LLMClient.java`	Create	LLM client interface
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/llm/AnthropicClient.java`	Create	Anthropic implementation
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/llm/OpenAIClient.java`	Create	OpenAI implementation
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/llm/LocalClient.java`	Create	Ollama/local implementation
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/prompt/PromptBuilder.java`	Create	System/user prompt builder
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/prompt/ContextAssembler.java`	Create	Index context assembly
`qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/model/Plan.java`	Create	Plan output model
`qctl-qstudio/src/main/resources/prompts/plan-system.txt`	Create	System prompt template

Implementation Tasks

Create PlanCommand with Picocli annotations
Add --file, --output, --provider, --dry-run, --estimate options
Define LLMClient interface
Implement AnthropicClient with Claude API
Implement OpenAIClient with GPT API
Implement LocalClient for Ollama
Create PromptBuilder with system prompt
Create ContextAssembler to include relevant index context
Parse LLM response into structured Plan
Write plan to markdown file
Add token counting and cost estimation
Implement streaming output for long responses
Write unit tests for PromptBuilder
Write integration tests with mock LLM

Acceptance Criteria

qstudio plan "<prompt>" generates implementation plan
Uses project index for context
Outputs structured markdown plan
Supports multiple LLM providers
--dry-run shows prompt without calling LLM
--estimate shows token/cost estimate
Saves plan to ledger automatically
Respects path policies (#52)

## User Story As a developer, I want to generate implementation plans using AI so I can get structured guidance on how to implement features in my QQQ project. ## Design ### Command Interface ```bash # Generate plan from prompt qstudio plan "Add a new Order entity with CRUD operations" # Generate plan from file qstudio plan --file requirements.md # Specify output location qstudio plan "Add authentication" --output docs/PLAN-auth.md # Use specific LLM provider qstudio plan "Add caching" --provider anthropic # Dry run (show what would be sent to LLM) qstudio plan "Add logging" --dry-run # Estimate tokens/cost qstudio plan "Add metrics" --estimate ``` ### Output Format (plan.md) ```markdown # Implementation Plan: Add Order Entity ## Overview Create a new Order entity with full CRUD operations following QQQ patterns. ## Files to Create | File | Purpose | |------|---------| | `src/.../model/Order.java` | RecordEntity for orders | | `src/.../metadata/OrderTableMetaDataProducer.java` | Table metadata | | `src/.../api/OrderApiMetaDataProducer.java` | API endpoints | ## Implementation Steps ### Step 1: Create Order Entity Create `Order.java` extending QRecord with fields: - id (Integer, primary key) - customerId (Integer, foreign key) - orderDate (LocalDate) - status (String) ### Step 2: Create Table Metadata ... ## Estimated Effort - Files: 4 - Lines of code: ~200 - Complexity: Low ## Generated - Date: 2024-01-15T10:30:00Z - Provider: anthropic/claude-3-opus - Tokens: 2,450 ``` ### LLM Provider Configuration ```yaml # ~/.qctl/qctl.yaml qstudio: default_provider: anthropic providers: anthropic: model: claude-3-opus-20240229 api_key: ${ANTHROPIC_API_KEY} openai: model: gpt-4-turbo api_key: ${OPENAI_API_KEY} local: endpoint: http://localhost:11434 model: codellama:34b ``` ## Files to Create/Modify | File | Action | Purpose | |------|--------|---------| | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/PlanCommand.java` | Create | Main plan command | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/llm/LLMClient.java` | Create | LLM client interface | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/llm/AnthropicClient.java` | Create | Anthropic implementation | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/llm/OpenAIClient.java` | Create | OpenAI implementation | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/llm/LocalClient.java` | Create | Ollama/local implementation | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/prompt/PromptBuilder.java` | Create | System/user prompt builder | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/prompt/ContextAssembler.java` | Create | Index context assembly | | `qctl-qstudio/src/main/java/io/qrun/qctl/qstudio/model/Plan.java` | Create | Plan output model | | `qctl-qstudio/src/main/resources/prompts/plan-system.txt` | Create | System prompt template | ## Implementation Tasks - [ ] Create PlanCommand with Picocli annotations - [ ] Add --file, --output, --provider, --dry-run, --estimate options - [ ] Define LLMClient interface - [ ] Implement AnthropicClient with Claude API - [ ] Implement OpenAIClient with GPT API - [ ] Implement LocalClient for Ollama - [ ] Create PromptBuilder with system prompt - [ ] Create ContextAssembler to include relevant index context - [ ] Parse LLM response into structured Plan - [ ] Write plan to markdown file - [ ] Add token counting and cost estimation - [ ] Implement streaming output for long responses - [ ] Write unit tests for PromptBuilder - [ ] Write integration tests with mock LLM ## Acceptance Criteria - [ ] `qstudio plan "<prompt>"` generates implementation plan - [ ] Uses project index for context - [ ] Outputs structured markdown plan - [ ] Supports multiple LLM providers - [ ] `--dry-run` shows prompt without calling LLM - [ ] `--estimate` shows token/cost estimate - [ ] Saves plan to ledger automatically - [ ] Respects path policies (#52)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qctl#51