Initial commit

2025-11-29 18:50:24 +08:00
commit f172746dc6
52 changed files with 17406 additions and 0 deletions
--- a/commands/init.py
+++ b/commands/init.py
@@ -0,0 +1 @@
+"""Claude command templates."""
--- a/commands/implement.md
+++ b/commands/implement.md
@@ -0,0 +1,164 @@
+---
+allowed-tools: [Read, Write, Edit, MultiEdit, Bash, Grep, Glob, TodoWrite, Task, Skill]
+description: "Execute specification-driven implementation with the implementing-features skill"
+---
+
+# /implement - Specification-Driven Implementation
+
+ARGUMENTS: $SPEC_ID_OR_DESCRIPTION
+
+## Purpose
+Invoke the implementing-features skill interactively to implement features following the complete specification-driven development process.
+
+## Usage
+```bash
+# Implement a specific specification by ID
+/implement spec-auth-001
+
+# Implement by description (will find/create spec)
+/implement "user authentication system"
+
+# Resume implementation
+/implement --resume
+```
+
+## Interactive Decision-Making
+
+I will ask clarifying questions to ensure you're in control:
+
+**Before Implementation:**
+- **Approach Selection**: When multiple valid approaches exist, I'll present 2-3 options with pros/cons for you to choose
+- **Scope Boundaries**: I'll confirm what's included/excluded from this implementation
+- **Trade-offs**: You'll decide priorities like speed vs simplicity, flexibility vs constraints
+- **Integration**: You'll choose how this connects to existing systems
+
+**During Planning:**
+- I'll present an implementation plan and WAIT for your approval before coding
+- You can request changes or alternative approaches
+
+**You maintain explicit control over key technical decisions.**
+
+## What This Does
+
+This command is a direct entry point to the **implementing-features** skill, which provides:
+
+1. **Specification-First Development**
+   - Loads or creates specifications
+   - Ensures acceptance criteria are clear
+   - Tracks progress automatically
+
+2. **Quality-Focused Implementation**
+   - Follows best practices and patterns
+   - Includes tests from the start
+   - Maintains code quality standards
+
+3. **Complete Lifecycle**
+   - Implementation → Testing → Documentation
+   - Progress tracking via TODOs
+   - Automatic spec updates
+
+## The Implementation Workflow
+
+The skill guides you through:
+
+```yaml
+workflow:
+  1_load_spec:
+    - Find or create specification
+    - Review acceptance criteria
+    - Set up TODO tracking
+
+  2_implement:
+    - Follow spec requirements
+    - Write tests alongside code
+    - Maintain quality standards
+
+  3_verify:
+    - Run tests
+    - Check acceptance criteria
+    - Update progress
+
+  4_complete:
+    - Mark criteria as complete
+    - Update documentation
+    - Move spec to completed
+```
+
+## When to Use
+
+**Use `/implement` when:**
+- You have a specification ready to implement
+- You want structured, guided implementation
+- You need automatic progress tracking
+- You want quality built-in from the start
+
+**Don't use when:**
+- Just exploring code (`/research` instead)
+- Quick fixes (direct edit is fine)
+- Planning phase (`/plan` instead)
+
+## Example Session
+
+```
+User: /implement spec-auth-001
+
+🔄 Loading specification: spec-auth-001
+📋 Title: User Authentication System
+✅ Acceptance Criteria:
+  1. [ ] Login endpoint accepts email/password
+  2. [ ] JWT tokens generated on successful login
+  3. [ ] Token validation middleware
+  4. [ ] Logout invalidates tokens
+  5. [ ] Password hashing with bcrypt
+
+🎯 Starting implementation workflow...
+
+[Skill invoked: implementing-features]
+
+📝 Creating TODO list for tracking...
+✓ Loaded implementation patterns
+✓ Loaded quality standards
+✓ Ready to implement
+
+Let's start with criterion 1: Login endpoint...
+```
+
+## Skill Integration
+
+This command loads and follows:
+- `@skills/implementing-features/SKILL.md` - Main workflow
+- `@skills/implementing-features/SPECS.md` - Spec handling
+- `@skills/implementing-features/QUALITY.md` - Quality standards
+- `@skills/implementing-features/WORKFLOW.md` - Step-by-step process
+- `@skills/implementing-features/AGENTS.md` - When to use agents
+
+## Arguments
+
+```yaml
+arguments:
+  spec_id:
+    description: "ID of specification to implement"
+    example: "spec-auth-001"
+    optional: true
+
+  description:
+    description: "Feature description (will find/create spec)"
+    example: "user authentication"
+    optional: true
+
+  --resume:
+    description: "Resume in-progress implementation"
+    example: "/implement --resume"
+```
+
+## Success Criteria
+
+Implementation is complete when:
+- ✅ All acceptance criteria checked off
+- ✅ Tests passing
+- ✅ Code follows quality standards
+- ✅ Documentation updated
+- ✅ Specification moved to completed
+
+---
+*This command invokes the implementing-features skill for structured, quality-focused development*
--- a/commands/plan.md
+++ b/commands/plan.md
@@ -0,0 +1,117 @@
+---
+allowed-tools: [Skill, Read, Grep, Glob, TodoWrite]
+description: "Create and manage specifications through skills-based planning"
+---
+
+# /plan - Lightweight Planning Router
+
+ARGUMENTS: $DESCRIPTION
+
+## Purpose
+Routes planning requests to specialized skills for specification creation and lifecycle management.
+
+## Usage
+```
+/plan                    # Create new specification (delegates to managing-specifications skill)
+/plan "User Auth"        # Create spec with title
+/plan --status          # Show dashboard (delegates to managing-specifications skill)
+```
+
+## Interactive Specification Creation
+
+The planning process is interactive - I'll ask clarifying questions to ensure the specification matches your intent:
+
+**What I'll Ask About:**
+- **Type & Scope**: What kind of work (feature/bugfix/refactor) and boundaries
+- **Approach**: If multiple valid approaches exist, you choose which direction
+- **Priorities**: Trade-offs between speed, simplicity, flexibility, maintainability
+- **Dependencies**: What must be done first, what this blocks
+- **Success Criteria**: How we'll know this is complete
+
+**You'll make key decisions through structured questions before I generate the specification.**
+
+## Execution
+
+This command is a lightweight router that delegates to appropriate skills based on the request:
+
+**Creating Specifications:**
+When you request a new spec, immediately invoke the **managing-specifications skill** with user requirements.
+
+**Managing Specifications:**
+When checking status or managing lifecycle (activate, complete, etc.), invoke the **managing-specifications skill**.
+
+**Creating Pull Requests:**
+When user mentions PR or wants to ship completed work, invoke the **reviewing-and-shipping skill**.
+
+## Routing Logic
+
+### Request Type Detection
+
+**New Specification:**
+- Pattern: `/plan`, `/plan "title"`, "create spec", "plan feature"
+- Action: Invoke `managing-specifications` skill
+- Pass: User requirements, title, description
+
+**Status Dashboard:**
+- Pattern: `/plan --status`, "show specs", "spec dashboard"
+- Action: Invoke `managing-specifications` skill with status mode
+- Returns: Progress overview, active specs, recommendations
+
+**Lifecycle Management:**
+- Pattern: "activate spec-X", "complete spec-X", "move spec-X"
+- Action: Invoke `managing-specifications` skill with spec ID
+- Operations: Draft→Active, Active→Completed, validation
+
+**Pull Request Creation:**
+- Pattern: "create pr", "ship spec", "pr for spec-X"
+- Action: Invoke `reviewing-and-shipping` skill with spec ID
+- Returns: Generated PR with rich context
+
+## Skill Delegation
+
+This command acts as a thin router. All detailed functionality is handled by skills:
+
+- **managing-specifications**: Interactive spec creation, requirement gathering, template generation, lifecycle management, progress tracking, status dashboard
+- **reviewing-and-shipping**: Pull request creation from completed specifications
+
+## Implementation Notes
+
+**No Complex Logic:**
+This command should only:
+1. Parse user intent from arguments
+2. Invoke the appropriate skill with Skill tool
+3. Pass through user requirements/parameters
+
+**Example Routing:**
+```
+User: /plan "User Authentication"
+→ Detect: New specification request
+→ Invoke: Skill("managing-specifications") with title="User Authentication"
+→ Skill handles: Requirements, criteria, file creation
+
+User: /plan --status
+→ Detect: Status dashboard request
+→ Invoke: Skill("managing-specifications") with mode="status"
+→ Skill handles: Progress calculation, display
+
+User: "activate spec-feature-001"
+→ Detect: Lifecycle management
+→ Invoke: Skill("managing-specifications") with operation="activate", spec="spec-feature-001"
+→ Skill handles: Validation, file moving, state updates
+```
+
+## Folder Structure Reference
+
+Specifications use folder-based state management:
+```
+.quaestor/specs/
+├── draft/      # Planned (unlimited)
+├── active/     # In progress (max 3)
+└── completed/  # Finished
+```
+
+**See managing-specifications skill for lifecycle details.**
+
+---
+
+*Simple, interactive specification planning powered by Agent Skills*
--- a/commands/research.md
+++ b/commands/research.md
@@ -0,0 +1,101 @@
+---
+allowed-tools: [Task, Read, Grep, Glob, TodoWrite]
+description: "Lightweight router for intelligent codebase exploration via researcher agent"
+---
+
+# /research - Codebase Exploration Router
+
+ARGUMENTS: $QUERY
+
+## Purpose
+Routes research queries to the specialized researcher agent for comprehensive codebase exploration and analysis.
+
+## Usage
+```
+/research "authentication patterns"
+/research "how does the payment system work"
+/research "user service dependencies"
+/research "find all API endpoints"
+```
+
+## Execution
+
+This command is a lightweight router that delegates all research to the **researcher agent** with appropriate thoroughness level.
+
+**Primary Agent: researcher**
+- Handles all codebase exploration
+- Pattern analysis and discovery
+- Dependency mapping
+- Code understanding
+
+**Supporting Agents (invoked by researcher when needed):**
+- architect: System design analysis
+- security: Security pattern review
+- Other agents as appropriate for the query
+
+## Routing Logic
+
+### Thoroughness Level Selection
+
+Automatically select thoroughness level based on query complexity:
+
+**Quick (simple queries):**
+```
+Pattern: "find X", "where is Y", "show Z"
+Thoroughness: "quick"
+Time: ~2 minutes
+```
+
+**Medium (standard queries):**
+```
+Pattern: "how does X work", "explain Y", "understand Z"
+Thoroughness: "medium"
+Time: ~5 minutes
+```
+
+**Very Thorough (complex queries):**
+```
+Pattern: "architecture of X", "full analysis of Y", "comprehensive review"
+Thoroughness: "very thorough"
+Time: ~10-15 minutes
+```
+
+### Agent Invocation
+
+**Always use Task tool with subagent_type=Explore:**
+```
+Task(
+  subagent_type="Explore",
+  description="Research [user query]",
+  prompt="[Full query with context and thoroughness level]"
+)
+```
+
+**Example:**
+```
+User: /research "authentication patterns"
+→ Detect: Pattern analysis request
+→ Thoroughness: "medium" (standard complexity)
+→ Invoke: Task(subagent_type="Explore", prompt="Research authentication patterns in the codebase at medium thoroughness. Identify all authentication implementations, patterns used, and provide examples with file locations.")
+```
+
+## Implementation Notes
+
+**No Direct Search:**
+This command should NOT perform grep/glob operations directly. All code exploration is delegated to the Explore agent.
+
+**Agent Handles:**
+- File discovery and pattern matching
+- Relevance scoring and ranking
+- Context building
+- Report generation
+- Follow-up suggestions
+
+**Command Responsibilities:**
+1. Parse user query
+2. Detect thoroughness level needed
+3. Invoke Explore agent via Task tool
+4. Return agent's findings to user
+
+---
+*Intelligent codebase exploration with multi-agent orchestration for deep understanding*