mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-10 17:11:04 +08:00
Add unit tests for various components and stores in the terminal dashboard
- Implement tests for AssociationHighlight, DashboardToolbar, QueuePanel, SessionGroupTree, and TerminalDashboardPage to ensure proper functionality and state management. - Create tests for cliSessionStore, issueQueueIntegrationStore, queueExecutionStore, queueSchedulerStore, sessionManagerStore, and terminalGridStore to validate state resets and workspace scoping. - Mock necessary dependencies and state management hooks to isolate tests and ensure accurate behavior.
This commit is contained in:
catlog22
298
.codex/skills/spec-generator/phases/02-product-brief.md
Normal file
298
.codex/skills/spec-generator/phases/02-product-brief.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# Phase 2: Product Brief
|
||||
|
||||
> **Execution Mode: Agent Delegated**
|
||||
> This phase is executed by a `doc-generator` agent. The orchestrator (SKILL.md) passes session context via the Task tool. The agent reads this file for instructions, executes all steps, writes output files, and returns a JSON summary.
|
||||
|
||||
Generate a product brief through multi-perspective CLI analysis, establishing "what" and "why".
|
||||
|
||||
## Objective
|
||||
|
||||
- Read Phase 1 outputs (spec-config.json, discovery-context.json)
|
||||
- Launch 3 parallel CLI analyses from product, technical, and user perspectives
|
||||
- Synthesize convergent themes and conflicting views
|
||||
- Optionally refine with user input
|
||||
- Generate product-brief.md using template
|
||||
|
||||
## Input
|
||||
|
||||
- Dependency: `{workDir}/spec-config.json`
|
||||
- Primary: `{workDir}/refined-requirements.json` (Phase 1.5 output, preferred over raw seed_analysis)
|
||||
- Optional: `{workDir}/discovery-context.json`
|
||||
- Config: `{workDir}/spec-config.json`
|
||||
- Template: `templates/product-brief.md`
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Load Phase 1 Context
|
||||
|
||||
```javascript
|
||||
const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
|
||||
const { seed_analysis, seed_input, has_codebase, depth, focus_areas } = specConfig;
|
||||
|
||||
// Load refined requirements (Phase 1.5 output) - preferred over raw seed_analysis
|
||||
let refinedReqs = null;
|
||||
try {
|
||||
refinedReqs = JSON.parse(Read(`${workDir}/refined-requirements.json`));
|
||||
} catch (e) {
|
||||
// No refined requirements, fall back to seed_analysis
|
||||
}
|
||||
|
||||
let discoveryContext = null;
|
||||
if (has_codebase) {
|
||||
try {
|
||||
discoveryContext = JSON.parse(Read(`${workDir}/discovery-context.json`));
|
||||
} catch (e) {
|
||||
// No discovery context available, proceed without
|
||||
}
|
||||
}
|
||||
|
||||
// Build shared context string for CLI prompts
|
||||
// Prefer refined requirements over raw seed_analysis
|
||||
const problem = refinedReqs?.clarified_problem_statement || seed_analysis.problem_statement;
|
||||
const users = refinedReqs?.confirmed_target_users?.map(u => u.name || u).join(', ')
|
||||
|| seed_analysis.target_users.join(', ');
|
||||
const domain = refinedReqs?.confirmed_domain || seed_analysis.domain;
|
||||
const constraints = refinedReqs?.boundary_conditions?.constraints?.join(', ')
|
||||
|| seed_analysis.constraints.join(', ');
|
||||
const features = refinedReqs?.confirmed_features?.map(f => f.name).join(', ') || '';
|
||||
const nfrs = refinedReqs?.non_functional_requirements?.map(n => `${n.type}: ${n.details}`).join('; ') || '';
|
||||
|
||||
const sharedContext = `
|
||||
SEED: ${seed_input}
|
||||
PROBLEM: ${problem}
|
||||
TARGET USERS: ${users}
|
||||
DOMAIN: ${domain}
|
||||
CONSTRAINTS: ${constraints}
|
||||
FOCUS AREAS: ${focus_areas.join(', ')}
|
||||
${features ? `CONFIRMED FEATURES: ${features}` : ''}
|
||||
${nfrs ? `NON-FUNCTIONAL REQUIREMENTS: ${nfrs}` : ''}
|
||||
${discoveryContext ? `
|
||||
CODEBASE CONTEXT:
|
||||
- Existing patterns: ${discoveryContext.existing_patterns?.slice(0,5).join(', ') || 'none'}
|
||||
- Architecture constraints: ${discoveryContext.architecture_constraints?.slice(0,3).join(', ') || 'none'}
|
||||
- Tech stack: ${JSON.stringify(discoveryContext.tech_stack || {})}
|
||||
` : ''}`;
|
||||
```
|
||||
|
||||
### Step 2: Multi-CLI Parallel Analysis (3 perspectives)
|
||||
|
||||
Launch 3 CLI calls in parallel:
|
||||
|
||||
**Product Perspective (Gemini)**:
|
||||
```javascript
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Product analysis for specification - identify market fit, user value, and success criteria.
|
||||
Success: Clear vision, measurable goals, competitive positioning.
|
||||
|
||||
${sharedContext}
|
||||
|
||||
TASK:
|
||||
- Define product vision (1-3 sentences, aspirational)
|
||||
- Analyze market/competitive landscape
|
||||
- Define 3-5 measurable success metrics
|
||||
- Identify scope boundaries (in-scope vs out-of-scope)
|
||||
- Assess user value proposition
|
||||
- List assumptions that need validation
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: Structured product analysis with: vision, goals with metrics, scope, competitive positioning, assumptions
|
||||
CONSTRAINTS: Focus on 'what' and 'why', not 'how'
|
||||
" --tool gemini --mode analysis`,
|
||||
run_in_background: true
|
||||
});
|
||||
```
|
||||
|
||||
**Technical Perspective (Codex)**:
|
||||
```javascript
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Technical feasibility analysis for specification - assess implementation viability and constraints.
|
||||
Success: Clear technical constraints, integration complexity, technology recommendations.
|
||||
|
||||
${sharedContext}
|
||||
|
||||
TASK:
|
||||
- Assess technical feasibility of the core concept
|
||||
- Identify technical constraints and blockers
|
||||
- Evaluate integration complexity with existing systems
|
||||
- Recommend technology approach (high-level)
|
||||
- Identify technical risks and dependencies
|
||||
- Estimate complexity: simple/moderate/complex
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: Technical analysis with: feasibility assessment, constraints, integration complexity, tech recommendations, risks
|
||||
CONSTRAINTS: Focus on feasibility and constraints, not detailed architecture
|
||||
" --tool codex --mode analysis`,
|
||||
run_in_background: true
|
||||
});
|
||||
```
|
||||
|
||||
**User Perspective (Claude)**:
|
||||
```javascript
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: User experience analysis for specification - understand user journeys, pain points, and UX considerations.
|
||||
Success: Clear user personas, journey maps, UX requirements.
|
||||
|
||||
${sharedContext}
|
||||
|
||||
TASK:
|
||||
- Elaborate user personas with goals and frustrations
|
||||
- Map primary user journey (happy path)
|
||||
- Identify key pain points in current experience
|
||||
- Define UX success criteria
|
||||
- List accessibility and usability considerations
|
||||
- Suggest interaction patterns
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: User analysis with: personas, journey map, pain points, UX criteria, interaction recommendations
|
||||
CONSTRAINTS: Focus on user needs and experience, not implementation
|
||||
" --tool claude --mode analysis`,
|
||||
run_in_background: true
|
||||
});
|
||||
|
||||
// STOP: Wait for all 3 CLI results before continuing
|
||||
```
|
||||
|
||||
### Step 3: Synthesize Perspectives
|
||||
|
||||
```javascript
|
||||
// After receiving all 3 CLI results:
|
||||
// Extract convergent themes (all agree)
|
||||
// Identify conflicting views (need resolution)
|
||||
// Note unique contributions from each perspective
|
||||
|
||||
const synthesis = {
|
||||
convergent_themes: [], // themes all 3 perspectives agree on
|
||||
conflicts: [], // areas where perspectives differ
|
||||
product_insights: [], // unique from product perspective
|
||||
technical_insights: [], // unique from technical perspective
|
||||
user_insights: [] // unique from user perspective
|
||||
};
|
||||
```
|
||||
|
||||
### Step 4: Interactive Refinement (Optional)
|
||||
|
||||
```javascript
|
||||
if (!autoMode) {
|
||||
// Present synthesis summary to user
|
||||
// AskUserQuestion with:
|
||||
// - Confirm vision statement
|
||||
// - Resolve any conflicts between perspectives
|
||||
// - Adjust scope if needed
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Review the synthesized product brief. Any adjustments needed?",
|
||||
header: "Review",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Looks good", description: "Proceed to PRD generation" },
|
||||
{ label: "Adjust scope", description: "Narrow or expand the scope" },
|
||||
{ label: "Revise vision", description: "Refine the vision statement" }
|
||||
]
|
||||
}
|
||||
]
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Generate product-brief.md
|
||||
|
||||
```javascript
|
||||
// Read template
|
||||
const template = Read('templates/product-brief.md');
|
||||
|
||||
// Fill template with synthesized content
|
||||
// Apply document-standards.md formatting rules
|
||||
// Write with YAML frontmatter
|
||||
|
||||
const frontmatter = `---
|
||||
session_id: ${specConfig.session_id}
|
||||
phase: 2
|
||||
document_type: product-brief
|
||||
status: ${autoMode ? 'complete' : 'draft'}
|
||||
generated_at: ${new Date().toISOString()}
|
||||
stepsCompleted: ["load-context", "multi-cli-analysis", "synthesis", "generation"]
|
||||
version: 1
|
||||
dependencies:
|
||||
- spec-config.json
|
||||
---`;
|
||||
|
||||
// Combine frontmatter + filled template content
|
||||
Write(`${workDir}/product-brief.md`, `${frontmatter}\n\n${filledContent}`);
|
||||
|
||||
// Update spec-config.json
|
||||
specConfig.phasesCompleted.push({
|
||||
phase: 2,
|
||||
name: "product-brief",
|
||||
output_file: "product-brief.md",
|
||||
completed_at: new Date().toISOString()
|
||||
});
|
||||
Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
|
||||
```
|
||||
|
||||
### Step 5.5: Generate glossary.json
|
||||
|
||||
```javascript
|
||||
// Extract terminology from product brief and CLI analysis
|
||||
// Generate structured glossary for cross-document consistency
|
||||
|
||||
const glossary = {
|
||||
session_id: specConfig.session_id,
|
||||
terms: [
|
||||
// Extract from product brief content:
|
||||
// - Key domain nouns from problem statement
|
||||
// - User persona names
|
||||
// - Technical terms from multi-perspective synthesis
|
||||
// Each term should have:
|
||||
// { term: "...", definition: "...", aliases: [], first_defined_in: "product-brief.md", category: "core|technical|business" }
|
||||
]
|
||||
};
|
||||
|
||||
Write(`${workDir}/glossary.json`, JSON.stringify(glossary, null, 2));
|
||||
```
|
||||
|
||||
**Glossary Injection**: In all subsequent phase prompts, inject the following into the CONTEXT section:
|
||||
```
|
||||
TERMINOLOGY GLOSSARY (use these terms consistently):
|
||||
${JSON.stringify(glossary.terms, null, 2)}
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- **File**: `product-brief.md`
|
||||
- **Format**: Markdown with YAML frontmatter
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
- [ ] Vision statement: clear, 1-3 sentences
|
||||
- [ ] Problem statement: specific and measurable
|
||||
- [ ] Target users: >= 1 persona with needs
|
||||
- [ ] Goals: >= 2 with measurable metrics
|
||||
- [ ] Scope: in-scope and out-of-scope defined
|
||||
- [ ] Multi-perspective synthesis included
|
||||
- [ ] YAML frontmatter valid
|
||||
|
||||
## Next Phase
|
||||
|
||||
Proceed to [Phase 3: Requirements](03-requirements.md) with the generated product-brief.md.
|
||||
|
||||
---
|
||||
|
||||
## Agent Return Summary
|
||||
|
||||
When executed as a delegated agent, return the following JSON summary to the orchestrator:
|
||||
|
||||
```json
|
||||
{
|
||||
"phase": 2,
|
||||
"status": "complete",
|
||||
"files_created": ["product-brief.md", "glossary.json"],
|
||||
"quality_notes": ["list of any quality concerns or deviations"],
|
||||
"key_decisions": ["list of significant synthesis decisions made"]
|
||||
}
|
||||
```
|
||||
|
||||
The orchestrator will:
|
||||
1. Validate that listed files exist on disk
|
||||
2. Read `spec-config.json` to confirm `phasesCompleted` was updated
|
||||
3. Store the summary for downstream phase context
|
||||
Reference in New Issue
Block a user