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
274
.codex/skills/spec-generator/phases/04-architecture.md
Normal file
274
.codex/skills/spec-generator/phases/04-architecture.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# Phase 4: Architecture
|
||||
|
||||
> **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 technical architecture decisions, component design, and technology selections based on requirements.
|
||||
|
||||
## Objective
|
||||
|
||||
- Analyze requirements to identify core components and system architecture
|
||||
- Generate Architecture Decision Records (ADRs) with alternatives
|
||||
- Map architecture to existing codebase (if applicable)
|
||||
- Challenge architecture via Codex CLI review
|
||||
- Generate architecture.md using template
|
||||
|
||||
## Input
|
||||
|
||||
- Dependency: `{workDir}/requirements/_index.md` (and individual `REQ-*.md` files)
|
||||
- Reference: `{workDir}/product-brief.md`
|
||||
- Optional: `{workDir}/discovery-context.json`
|
||||
- Config: `{workDir}/spec-config.json`
|
||||
- Template: `templates/architecture-doc.md`
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: Load Phase 2-3 Context
|
||||
|
||||
```javascript
|
||||
const specConfig = JSON.parse(Read(`${workDir}/spec-config.json`));
|
||||
const productBrief = Read(`${workDir}/product-brief.md`);
|
||||
const requirements = Read(`${workDir}/requirements.md`);
|
||||
|
||||
let discoveryContext = null;
|
||||
if (specConfig.has_codebase) {
|
||||
try {
|
||||
discoveryContext = JSON.parse(Read(`${workDir}/discovery-context.json`));
|
||||
} catch (e) { /* no context */ }
|
||||
}
|
||||
|
||||
// Load glossary for terminology consistency
|
||||
let glossary = null;
|
||||
try {
|
||||
glossary = JSON.parse(Read(`${workDir}/glossary.json`));
|
||||
} catch (e) { /* proceed without */ }
|
||||
|
||||
// Load spec type profile for specialized sections
|
||||
const specType = specConfig.spec_type || 'service';
|
||||
let profile = null;
|
||||
try {
|
||||
profile = Read(`templates/profiles/${specType}-profile.md`);
|
||||
} catch (e) { /* use base template only */ }
|
||||
```
|
||||
|
||||
### Step 2: Architecture Analysis via Gemini CLI
|
||||
|
||||
```javascript
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Generate technical architecture for the specified requirements.
|
||||
Success: Complete component architecture, tech stack, and ADRs with justified decisions.
|
||||
|
||||
PRODUCT BRIEF (summary):
|
||||
${productBrief.slice(0, 3000)}
|
||||
|
||||
REQUIREMENTS:
|
||||
${requirements.slice(0, 5000)}
|
||||
|
||||
${discoveryContext ? `EXISTING CODEBASE:
|
||||
- Tech stack: ${JSON.stringify(discoveryContext.tech_stack || {})}
|
||||
- Existing patterns: ${discoveryContext.existing_patterns?.slice(0,5).join('; ') || 'none'}
|
||||
- Architecture constraints: ${discoveryContext.architecture_constraints?.slice(0,3).join('; ') || 'none'}
|
||||
` : ''}
|
||||
|
||||
TASK:
|
||||
- Define system architecture style (monolith, microservices, serverless, etc.) with justification
|
||||
- Identify core components and their responsibilities
|
||||
- Create component interaction diagram (Mermaid graph TD format)
|
||||
- Specify technology stack: languages, frameworks, databases, infrastructure
|
||||
- Generate 2-4 Architecture Decision Records (ADRs):
|
||||
- Each ADR: context, decision, 2-3 alternatives with pros/cons, consequences
|
||||
- Focus on: data storage, API design, authentication, key technical choices
|
||||
- Define data model: key entities and relationships (Mermaid erDiagram format)
|
||||
- Identify security architecture: auth, authorization, data protection
|
||||
- List API endpoints (high-level)
|
||||
${discoveryContext ? '- Map new components to existing codebase modules' : ''}
|
||||
- For each core entity with a lifecycle, create an ASCII state machine diagram showing:
|
||||
- All states and transitions
|
||||
- Trigger events for each transition
|
||||
- Side effects of transitions
|
||||
- Error states and recovery paths
|
||||
- Define a Configuration Model: list all configurable fields with name, type, default value, constraint, and description
|
||||
- Define Error Handling strategy:
|
||||
- Classify errors (transient/permanent/degraded)
|
||||
- Per-component error behavior using RFC 2119 keywords
|
||||
- Recovery mechanisms
|
||||
- Define Observability requirements:
|
||||
- Key metrics (name, type: counter/gauge/histogram, labels)
|
||||
- Structured log format and key log events
|
||||
- Health check endpoints
|
||||
\${profile ? \`
|
||||
SPEC TYPE PROFILE REQUIREMENTS (\${specType}):
|
||||
\${profile}
|
||||
\` : ''}
|
||||
\${glossary ? \`
|
||||
TERMINOLOGY GLOSSARY (use consistently):
|
||||
\${JSON.stringify(glossary.terms, null, 2)}
|
||||
\` : ''}
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: Complete architecture with: style justification, component diagram, tech stack table, ADRs, data model, security controls, API overview
|
||||
CONSTRAINTS: Architecture must support all Must-have requirements. Prefer proven technologies over cutting-edge.
|
||||
" --tool gemini --mode analysis`,
|
||||
run_in_background: true
|
||||
});
|
||||
|
||||
// Wait for CLI result
|
||||
```
|
||||
|
||||
### Step 3: Architecture Review via Codex CLI
|
||||
|
||||
```javascript
|
||||
// After receiving Gemini analysis, challenge it with Codex
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Critical review of proposed architecture - identify weaknesses and risks.
|
||||
Success: Actionable feedback with specific concerns and improvement suggestions.
|
||||
|
||||
PROPOSED ARCHITECTURE:
|
||||
${geminiArchitectureOutput.slice(0, 5000)}
|
||||
|
||||
REQUIREMENTS CONTEXT:
|
||||
${requirements.slice(0, 2000)}
|
||||
|
||||
TASK:
|
||||
- Challenge each ADR: are the alternatives truly the best options?
|
||||
- Identify scalability bottlenecks in the component design
|
||||
- Assess security gaps: authentication, authorization, data protection
|
||||
- Evaluate technology choices: maturity, community support, fit
|
||||
- Check for over-engineering or under-engineering
|
||||
- Verify architecture covers all Must-have requirements
|
||||
- Rate overall architecture quality: 1-5 with justification
|
||||
|
||||
MODE: analysis
|
||||
EXPECTED: Architecture review with: per-ADR feedback, scalability concerns, security gaps, technology risks, quality rating
|
||||
CONSTRAINTS: Be genuinely critical, not just validating. Focus on actionable improvements.
|
||||
" --tool codex --mode analysis`,
|
||||
run_in_background: true
|
||||
});
|
||||
|
||||
// Wait for CLI result
|
||||
```
|
||||
|
||||
### Step 4: Interactive ADR Decisions (Optional)
|
||||
|
||||
```javascript
|
||||
if (!autoMode) {
|
||||
// Present ADRs with review feedback to user
|
||||
// For each ADR where review raised concerns:
|
||||
AskUserQuestion({
|
||||
questions: [
|
||||
{
|
||||
question: "Architecture review raised concerns. How should we proceed?",
|
||||
header: "ADR Review",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Accept as-is", description: "Architecture is sound, proceed" },
|
||||
{ label: "Incorporate feedback", description: "Adjust ADRs based on review" },
|
||||
{ label: "Simplify", description: "Reduce complexity, fewer components" }
|
||||
]
|
||||
}
|
||||
]
|
||||
});
|
||||
// Apply user decisions to architecture
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Codebase Integration Mapping (Conditional)
|
||||
|
||||
```javascript
|
||||
if (specConfig.has_codebase && discoveryContext) {
|
||||
// Map new architecture components to existing code
|
||||
const integrationMapping = discoveryContext.relevant_files.map(f => ({
|
||||
new_component: "...", // matched from architecture
|
||||
existing_module: f.path,
|
||||
integration_type: "Extend|Replace|New",
|
||||
notes: f.rationale
|
||||
}));
|
||||
// Include in architecture document
|
||||
}
|
||||
```
|
||||
|
||||
### Step 6: Generate architecture/ directory
|
||||
|
||||
```javascript
|
||||
const template = Read('templates/architecture-doc.md');
|
||||
|
||||
// Create architecture directory
|
||||
Bash(`mkdir -p "${workDir}/architecture"`);
|
||||
|
||||
const status = autoMode ? 'complete' : 'draft';
|
||||
const timestamp = new Date().toISOString();
|
||||
|
||||
// Parse CLI outputs into structured ADRs
|
||||
const adrs = parseADRs(geminiArchitectureOutput, codexReviewOutput); // [{id, slug, title, ...}]
|
||||
|
||||
// Step 6a: Write individual ADR-*.md files (one per decision)
|
||||
adrs.forEach(adr => {
|
||||
// Use ADR-NNN-{slug}.md template from templates/architecture-doc.md
|
||||
// Fill: id, title, status, context, decision, alternatives, consequences, traces
|
||||
Write(`${workDir}/architecture/ADR-${adr.id}-${adr.slug}.md`, adrContent);
|
||||
});
|
||||
|
||||
// Step 6b: Write _index.md (overview + components + tech stack + links to ADRs)
|
||||
// Use _index.md template from templates/architecture-doc.md
|
||||
// Fill: system overview, component diagram, tech stack, ADR links table,
|
||||
// data model, API design, security controls, infrastructure, codebase integration
|
||||
Write(`${workDir}/architecture/_index.md`, indexContent);
|
||||
|
||||
// Update spec-config.json
|
||||
specConfig.phasesCompleted.push({
|
||||
phase: 4,
|
||||
name: "architecture",
|
||||
output_dir: "architecture/",
|
||||
output_index: "architecture/_index.md",
|
||||
file_count: adrs.length + 1,
|
||||
completed_at: timestamp
|
||||
});
|
||||
Write(`${workDir}/spec-config.json`, JSON.stringify(specConfig, null, 2));
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- **Directory**: `architecture/`
|
||||
- `_index.md` — Overview, component diagram, tech stack, data model, security, links
|
||||
- `ADR-NNN-{slug}.md` — Individual Architecture Decision Record (per ADR)
|
||||
- **Format**: Markdown with YAML frontmatter, cross-linked to requirements via relative paths
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
- [ ] Component diagram present in `_index.md` (Mermaid or ASCII)
|
||||
- [ ] Tech stack specified (languages, frameworks, key libraries)
|
||||
- [ ] >= 1 ADR file with alternatives considered
|
||||
- [ ] Each ADR file lists >= 2 options
|
||||
- [ ] `_index.md` ADR table links to all individual ADR files
|
||||
- [ ] Integration points identified
|
||||
- [ ] Data model described
|
||||
- [ ] Codebase mapping present (if has_codebase)
|
||||
- [ ] All files have valid YAML frontmatter
|
||||
- [ ] ADR files link back to requirement files
|
||||
|
||||
## Next Phase
|
||||
|
||||
Proceed to [Phase 5: Epics & Stories](05-epics-stories.md) with the generated architecture.md.
|
||||
|
||||
---
|
||||
|
||||
## Agent Return Summary
|
||||
|
||||
When executed as a delegated agent, return the following JSON summary to the orchestrator:
|
||||
|
||||
```json
|
||||
{
|
||||
"phase": 4,
|
||||
"status": "complete",
|
||||
"files_created": ["architecture/_index.md", "architecture/ADR-001-*.md", "..."],
|
||||
"file_count": 0,
|
||||
"codex_review_rating": 0,
|
||||
"quality_notes": ["list of quality concerns or review feedback addressed"],
|
||||
"key_decisions": ["architecture style choice", "key ADR decisions"]
|
||||
}
|
||||
```
|
||||
|
||||
The orchestrator will:
|
||||
1. Validate that `architecture/` directory exists with `_index.md` and ADR files
|
||||
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