Skip to content

Commit 167a5f4

Browse files
dugshubdugshub
committed
Refactor CLI entry point, enhance subprocess executor, and implement composable parser system for improved interaction paradigms
1 parent 5d4da15 commit 167a5f4

File tree

11 files changed

+490
-28
lines changed

11 files changed

+490
-28
lines changed

‎.claude/commands/plan/refine-issue.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
description: Collaboratively refine and plan a development issue through iterative exploration
3+
argument-hint: [issue-id] or leave blank to choose from available issues
4+
allowed-tools: Bash(tp:*), Read, Write, MultiEdit, Glob, Grep, WebFetch
5+
---
6+
7+
# Issue Refinement Process
8+
9+
You are beginning an iterative refinement session for a development issue. This is a collaborative exploration where you'll work with the user to deeply understand requirements, explore options, and make implementation decisions together.
10+
11+
## Phase 1: Context Gathering
12+
13+
### Step 1.1: Identify the Issue
14+
$ARGUMENTS
15+
16+
If an issue ID was provided (e.g., CLI-8), use:
17+
```bash
18+
tp show $1
19+
```
20+
21+
If no issue specified, show available work:
22+
```bash
23+
tp c
24+
```
25+
26+
**Important:** Check the team context in the output. Use the correct team filter if needed (e.g., `teams: CLI`).
27+
28+
### Step 1.2: Read Related Issues
29+
If there's a clear task hierarchy or related issues mentioned, read them to understand the broader context:
30+
- Look for dependencies mentioned in the ticket
31+
- Check for "blocked by" or "blocks" relationships
32+
- Review any parent epics or related work
33+
34+
### Step 1.3: Explore Existing Code
35+
Based on the issue context, explore relevant code:
36+
- Use `Glob` to find related files
37+
- Use `Read` to understand current implementation
38+
- Look for patterns already established in the codebase
39+
40+
## Phase 2: Initial Understanding
41+
42+
### Step 2.1: Summarize Your Understanding
43+
Present to the user:
44+
1. **What you understand** the issue is asking for
45+
2. **What questions** you have about requirements
46+
3. **What context** you might be missing
47+
48+
**Be honest about uncertainties.** Say things like:
49+
- "I'm not sure if this means X or Y..."
50+
- "Should we consider..."
51+
- "I notice the ticket mentions X but I don't see where that fits..."
52+
53+
### Step 2.2: Wait for User Input
54+
**PAUSE HERE** - Let the user provide additional context, corrections, or guidance.
55+
56+
## Phase 3: Iterative Exploration
57+
58+
### Step 3.1: Present Options
59+
Based on user feedback, present different approaches:
60+
61+
**Start simple and high-level:**
62+
```
63+
"So we could approach this in a few ways:
64+
65+
Option A: [Simple approach]
66+
- Pros: Quick to implement, easy to understand
67+
- Cons: Limited flexibility
68+
69+
Option B: [More complex approach]
70+
- Pros: More powerful, extensible
71+
- Cons: Takes longer, more complexity
72+
73+
What resonates with you?"
74+
```
75+
76+
### Step 3.2: Drill Down Gradually
77+
As the user expresses preferences, go deeper:
78+
1. Start with conceptual choices
79+
2. Move to architectural decisions
80+
3. Then implementation details
81+
4. Finally, specific code patterns
82+
83+
**Example progression:**
84+
- "Should this be interactive or command-based?"
85+
- "Would you prefer a class-based or functional approach?"
86+
- "Should we use Python's shlex for parsing or write our own?"
87+
88+
### Step 3.3: Show Code Examples
89+
When discussing options, provide small, concrete examples:
90+
```python
91+
# "Here's what Option A might look like:"
92+
def simple_parse(input):
93+
return input.split()
94+
95+
# "Versus Option B:"
96+
class Parser:
97+
def parse(self, input):
98+
# More sophisticated parsing
99+
```
100+
101+
## Phase 4: Convergence
102+
103+
### Step 4.1: Confirm Understanding
104+
Once you've explored options together, summarize:
105+
- The approach you've agreed on
106+
- Key decisions made
107+
- Any remaining open questions
108+
109+
### Step 4.2: Create Refinement Plan
110+
Write out a clear implementation plan with:
111+
1. **Phases** - Logical chunks of work
112+
2. **Components** - What needs to be built
113+
3. **Examples** - How it will be used
114+
4. **Acceptance Criteria** - How we'll know it's done
115+
116+
## Phase 5: Documentation
117+
118+
### Step 5.1: Create ADR if Needed
119+
If you made significant architectural decisions, create an ADR:
120+
```bash
121+
Write cli-patterns-docs/adrs/ADR-XXX-[decision-name].md
122+
```
123+
124+
Include:
125+
- Context of the decision
126+
- Options considered
127+
- Decision made and rationale
128+
- Consequences
129+
130+
### Step 5.2: Update the Issue
131+
Add a comment to the issue (if using Linear/GitHub) summarizing:
132+
- Decisions made during refinement
133+
- Updated implementation plan
134+
- Any new acceptance criteria
135+
- Links to ADRs created
136+
137+
### Step 5.3: Update Project Documentation
138+
If this refinement revealed important context:
139+
- Update CLAUDE.md if it affects how to work with the codebase
140+
- Add to relevant documentation
141+
- Create examples if helpful
142+
143+
## Important Principles
144+
145+
### Go Slow
146+
- Don't jump to implementation details
147+
- Start with understanding the problem
148+
- Build context gradually
149+
150+
### Be Collaborative
151+
- Present options, don't prescribe solutions
152+
- Ask "What do you think?" frequently
153+
- Admit when you're unsure
154+
155+
### Think About the System
156+
Remember: CLI Patterns is a system for building CLI systems. Consider:
157+
- How this feature enables different interaction paradigms
158+
- Whether components can be composable/reusable
159+
- How different users might combine features
160+
161+
### Document Thinking
162+
- Capture not just what was decided, but why
163+
- Note alternatives considered
164+
- Record constraints and trade-offs
165+
166+
## Example Session Flow
167+
168+
```
169+
1. "Let me look at CLI-8... [reads ticket]"
170+
2. "So this is about parsing commands. I see we currently have basic splitting. What kind of command styles do you envision supporting?"
171+
3. [User explains]
172+
4. "Interesting! So we need multiple paradigms. Let me show you some options..."
173+
5. [Explore together]
174+
6. "OK, so we're going with a composable parser system. Let me document this..."
175+
7. [Create ADR, update issue]
176+
```
177+
178+
## Completion Checklist
179+
180+
Before ending the refinement session, ensure:
181+
- [ ] Issue requirements are clear
182+
- [ ] Implementation approach is agreed upon
183+
- [ ] Key decisions are documented in ADRs
184+
- [ ] Issue is updated with refinement outcomes
185+
- [ ] Any new context is added to project docs
186+
- [ ] Next steps are clear
187+
188+
Remember: The goal is not just to refine the issue, but to build shared understanding through collaborative exploration.

‎cli-patterns-docs/adrs/ADR-007-composable-parser-system.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# ADR-007: Composable Parser System for Multiple Interaction Paradigms
2+
3+
## Status
4+
Accepted
5+
6+
## Date
7+
2024-01-25
8+
9+
## Context
10+
11+
During the refinement of CLI-8 (Basic Command Parser), we discovered that CLI Patterns is not building a single CLI interface, but rather a **system for building CLI systems**. Different use cases require fundamentally different interaction paradigms:
12+
13+
1. **Free-form text** (like Claude Code with `/` and `!` commands)
14+
2. **Smart augmentation** (wrapping existing CLIs like `dbt` with autocomplete)
15+
3. **Pure navigation** (arrow-key driven menus with no typing)
16+
17+
These paradigms need to coexist and even blend within a single session. A user might start in a navigation menu, select an option that drops them into an augmented dbt wrapper, then switch to free-form text for complex queries.
18+
19+
## Decision
20+
21+
We will build CLI-8 as a **composable parser system** rather than a monolithic command parser. This system will support multiple interaction modes that can be activated based on context.
22+
23+
### Core Architecture
24+
25+
```python
26+
class InteractionMode(Enum):
27+
TEXT = "text" # Free-form commands
28+
AUGMENTED = "smart" # Autocomplete wrappers
29+
NAVIGATION = "menu" # Pure arrow keys
30+
31+
class Parser(Protocol):
32+
"""All parsers implement this interface"""
33+
def can_parse(self, input: str, context: Context) -> bool:
34+
def parse(self, input: str, context: Context) -> ParseResult:
35+
def get_suggestions(self, partial: str) -> List[str]:
36+
37+
class ParserPipeline:
38+
"""Composable parser system"""
39+
def add_parser(self, parser: Parser, condition: Callable):
40+
def parse(self, input: str, context: Context):
41+
```
42+
43+
### Key Components
44+
45+
1. **Mode Manager** - Switches between interaction modes dynamically
46+
2. **Parser Chain** - Routes input to appropriate parser based on context
47+
3. **Suggestion Engine** - Powers autocomplete across modes
48+
4. **Navigation Controller** - Handles arrow-key navigation
49+
5. **Context Tracker** - Maintains state about where we are in the interaction
50+
51+
## Alternatives Considered
52+
53+
### Alternative 1: Single Monolithic Parser
54+
Build one parser that handles all cases with flags and options.
55+
56+
**Rejected because:**
57+
- Would become unwieldy as we add more modes
58+
- Hard to maintain clear separation of concerns
59+
- Difficult for wizard authors to customize
60+
61+
### Alternative 2: Separate Tools
62+
Build completely separate tools for each interaction mode.
63+
64+
**Rejected because:**
65+
- Users want to mix modes within a session
66+
- Would duplicate significant code
67+
- Hard to maintain consistent theming and behavior
68+
69+
### Alternative 3: Configuration-Based
70+
Use YAML/JSON to configure a single parser's behavior.
71+
72+
**Rejected because:**
73+
- Not flexible enough for complex interactions
74+
- Hard to express dynamic mode switching
75+
- Would limit extensibility
76+
77+
## Consequences
78+
79+
### Positive
80+
- **Flexibility**: Wizard authors can mix and match interaction modes
81+
- **Extensibility**: New parsers can be added without touching existing code
82+
- **Clarity**: Each parser has a single responsibility
83+
- **Testability**: Parsers can be tested in isolation
84+
- **User Experience**: Seamless transitions between modes
85+
86+
### Negative
87+
- **Complexity**: More moving parts than a simple parser
88+
- **Learning Curve**: Developers need to understand the composition model
89+
- **Coordination**: Parsers need to coordinate through shared context
90+
91+
### Neutral
92+
- Changes the mental model from "parsing commands" to "managing interactions"
93+
- Requires thinking about state and context more explicitly
94+
- Influences how we structure the wizard definition system
95+
96+
## Implementation Notes
97+
98+
1. Start with basic `TextParser` for free-form commands
99+
2. Add `ShellParser` for `!` prefix shell passthrough
100+
3. Implement `AutocompleteParser` for smart augmentation
101+
4. Build `NavigationParser` for menu-driven interaction
102+
5. Create `ModeSwitcher` to transition between modes
103+
104+
Each parser should:
105+
- Use the design token system for consistent theming
106+
- Integrate with the subprocess executor for command execution
107+
- Support async operations
108+
- Provide rich error messages with suggestions
109+
110+
## References
111+
112+
- CLI-8: Basic Command Parser ticket
113+
- CLI Patterns PRD (Product Requirements Document)
114+
- Prompt_toolkit documentation for input handling
115+
- Rich documentation for output formatting
116+
117+
## Follow-up Actions
118+
119+
1. Update CLI-8 ticket with composable parser design
120+
2. Create sub-tickets for each parser implementation
121+
3. Design the Context and Session state management
122+
4. Document parser authoring guide for developers

0 commit comments

Comments
 (0)