Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/agent-teams-lite/llms.txt
Use this file to discover all available pages before exploring further.
The sdd-explore sub-agent investigates the codebase, analyzes approaches, and returns a structured exploration report. It’s the research phase of SDD.
When It’s Triggered
The orchestrator launches sdd-explore when:
- User wants to investigate a feature or idea before implementing
- User says “/sdd-explore [topic]”
- As the first step of
/sdd-new workflow
- User asks “how would I implement X?” or “what’s the best way to…”
What It Does
Step 1: Understand the Request
Parses what the user wants to explore:
- Is this a new feature? A bug fix? A refactor?
- What domain does it touch?
- What’s the high-level goal?
Step 2: Investigate the Codebase
Reads relevant code to understand:
- Current architecture and patterns
- Files and modules that would be affected
- Existing behavior that relates to the request
- Potential constraints or risks
The sub-agent uses file search and code reading tools to gather context. It never guesses — it reads actual code.
Step 3: Analyze Options
If there are multiple approaches, compares them:
| Approach | Pros | Cons | Complexity |
|---|
| Option A | … | … | Low/Med/High |
| Option B | … | … | Low/Med/High |
Step 4: Optionally Save Exploration
- If the orchestrator provided a change name (part of
/sdd-new), saves analysis to openspec/changes/{change-name}/exploration.md (or Engram)
- If no change name (standalone
/sdd-explore), returns analysis without creating files
Step 5: Return Structured Analysis
Returns a result envelope with exploration findings.
Result Envelope Example
## Exploration: Add Dark Mode
### Current State
The app uses a static CSS theme defined in `src/styles/theme.css`. Color variables are hardcoded with light theme values. No theming infrastructure exists.
### Affected Areas
- `src/styles/theme.css` — Contains hardcoded color values
- `src/components/App.tsx` — Would need theme provider wrapper
- `src/hooks/` — New `useTheme` hook needed
- `localStorage` — For theme persistence
### Approaches
1. **CSS Variables + React Context** — Use CSS custom properties toggled via React context
- Pros: Native CSS, performant, no runtime overhead for style switching
- Cons: IE11 compatibility (not a concern for modern apps)
- Effort: Low
2. **CSS-in-JS (Styled Components)** — Replace static CSS with styled-components theming
- Pros: Type-safe themes, scoped styles, dynamic theming
- Cons: Requires refactoring all components, larger bundle size
- Effort: High
3. **Tailwind Dark Mode** — Use Tailwind's built-in dark mode classes
- Pros: Already using Tailwind, minimal setup
- Cons: Requires adding dark: prefix to every element, manual work
- Effort: Medium
### Recommendation
**CSS Variables + React Context** (Option 1)
Why:
- Lowest effort for the benefit
- Leverages existing CSS structure
- Performant (no JS in rendering path)
- Easy to extend later
### Risks
- Need to ensure all color values use CSS variables (currently ~30 hardcoded colors)
- SSR flash if theme applied after hydration (can be mitigated with inline script)
### Ready for Proposal
Yes — we have enough context to create a proposal. Recommend proceeding with `/sdd-propose` using Option 1 as the approach.
## Exploration: {topic}
### Current State
{How the system works today relevant to this topic}
### Affected Areas
- `path/to/file.ext` — {why it's affected}
- `path/to/other.ext` — {why it's affected}
### Approaches
1. **{Approach name}** — {brief description}
- Pros: {list}
- Cons: {list}
- Effort: {Low/Medium/High}
2. **{Approach name}** — {brief description}
- Pros: {list}
- Cons: {list}
- Effort: {Low/Medium/High}
### Recommendation
{Your recommended approach and why}
### Risks
- {Risk 1}
- {Risk 2}
### Ready for Proposal
{Yes/No — and what the orchestrator should tell the user}
Persistence Behavior
Standalone Exploration (no change name)
# User command
/sdd-explore "How to add authentication?"
# Explorer behavior
- Investigates codebase
- Returns analysis inline
- Does NOT create exploration.md
- Artifact store mode: irrelevant (nothing persisted)
Part of a Change (change name provided)
# User command
/sdd-new add-auth
# Orchestrator launches explorer with change_name="add-auth"
# Explorer behavior:
- Investigates codebase
- Saves to openspec/changes/add-auth/exploration.md (if openspec mode)
- OR saves to Engram as sdd/add-auth/explore (if engram mode)
- Returns analysis
Rules
- The ONLY file you MAY create is
exploration.md inside the change folder (if a change name is provided)
- DO NOT modify any existing code or files — this is read-only investigation
- ALWAYS read real code — never guess about the codebase
- Keep analysis CONCISE — the orchestrator needs a summary, not a novel
- If you can’t find enough information, say so clearly
- If the request is too vague, say what clarification is needed
- Return a structured envelope with:
status, executive_summary, detailed_report, artifacts, next_recommended, and risks
