mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-28 09:23:08 +08:00
feat: add templates for architecture documents, epics, product briefs, and requirements PRD
- Introduced architecture document template for Phase 4, including structure and individual ADR records. - Added epics & stories template for Phase 5, detailing epic breakdown and dependencies. - Created product brief template for Phase 2, summarizing product vision, problem statement, and target users. - Developed requirements PRD template for Phase 3, outlining functional and non-functional requirements with traceability. - Implemented spec command for project spec management with subcommands for loading, listing, rebuilding, and initializing specs.
This commit is contained in:
catlog22
@@ -0,0 +1,193 @@
|
||||
# Command: assess
|
||||
|
||||
## Purpose
|
||||
|
||||
Multi-mode architecture assessment. Auto-detects consultation mode from task subject prefix, runs mode-specific analysis, and produces a verdict with concerns and recommendations.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
### Common Context (all modes)
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session folder | Task description `Session:` field | Yes |
|
||||
| Wisdom | `<session_folder>/wisdom/` (all files) | No |
|
||||
| Project tech | `.workflow/project-tech.json` | No |
|
||||
| Explorations | `<session_folder>/explorations/` | No |
|
||||
|
||||
### Mode-Specific Context
|
||||
|
||||
| Mode | Task Pattern | Additional Context |
|
||||
|------|-------------|-------------------|
|
||||
| spec-review | ARCH-SPEC-* | `spec/architecture/_index.md`, `spec/architecture/ADR-*.md` |
|
||||
| plan-review | ARCH-PLAN-* | `plan/plan.json`, `plan/.task/TASK-*.json` |
|
||||
| code-review | ARCH-CODE-* | `git diff --name-only`, changed file contents |
|
||||
| consult | ARCH-CONSULT-* | Question extracted from task description |
|
||||
| feasibility | ARCH-FEASIBILITY-* | Proposal from task description, codebase search results |
|
||||
|
||||
## Phase 3: Mode-Specific Assessment
|
||||
|
||||
### Mode: spec-review
|
||||
|
||||
Review architecture documents for technical soundness across 4 dimensions.
|
||||
|
||||
**Assessment dimensions**:
|
||||
|
||||
| Dimension | Weight | Focus |
|
||||
|-----------|--------|-------|
|
||||
| Consistency | 25% | ADR decisions align with each other and with architecture index |
|
||||
| Scalability | 25% | Design supports growth, no single-point bottlenecks |
|
||||
| Security | 25% | Auth model, data protection, API security addressed |
|
||||
| Tech fitness | 25% | Technology choices match project-tech.json and problem domain |
|
||||
|
||||
**Checks**:
|
||||
- Read architecture index and all ADR files
|
||||
- Cross-reference ADR decisions for contradictions
|
||||
- Verify tech choices align with project-tech.json
|
||||
- Score each dimension 0-100
|
||||
|
||||
---
|
||||
|
||||
### Mode: plan-review
|
||||
|
||||
Review implementation plan for architectural soundness.
|
||||
|
||||
**Checks**:
|
||||
|
||||
| Check | What | Severity if Failed |
|
||||
|-------|------|-------------------|
|
||||
| Dependency cycles | Build task graph, detect cycles via DFS | High |
|
||||
| Task granularity | Flag tasks touching >8 files | Medium |
|
||||
| Convention compliance | Verify plan follows wisdom/conventions.md | Medium |
|
||||
| Architecture alignment | Verify plan doesn't contradict wisdom/decisions.md | High |
|
||||
|
||||
**Dependency cycle detection flow**:
|
||||
1. Parse all TASK-*.json files -> extract id and depends_on
|
||||
2. Build directed graph
|
||||
3. DFS traversal -> flag any node visited twice in same stack
|
||||
4. Report cycle path if found
|
||||
|
||||
---
|
||||
|
||||
### Mode: code-review
|
||||
|
||||
Assess architectural impact of code changes.
|
||||
|
||||
**Checks**:
|
||||
|
||||
| Check | Method | Severity if Found |
|
||||
|-------|--------|-------------------|
|
||||
| Layer violations | Detect upward imports (deeper layer importing shallower) | High |
|
||||
| New dependencies | Parse package.json diff for added deps | Medium |
|
||||
| Module boundary changes | Flag index.ts/index.js modifications | Medium |
|
||||
| Architectural impact | Score based on file count and boundary changes | Info |
|
||||
|
||||
**Impact scoring**:
|
||||
|
||||
| Condition | Impact Level |
|
||||
|-----------|-------------|
|
||||
| Changed files > 10 | High |
|
||||
| index.ts/index.js or package.json modified | Medium |
|
||||
| All other cases | Low |
|
||||
|
||||
**Detection example** (find changed files):
|
||||
|
||||
```bash
|
||||
Bash(command="git diff --name-only HEAD~1 2>/dev/null || git diff --name-only --cached")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Mode: consult
|
||||
|
||||
Answer architecture decision questions. Route by question complexity.
|
||||
|
||||
**Complexity detection**:
|
||||
|
||||
| Condition | Classification |
|
||||
|-----------|---------------|
|
||||
| Question > 200 chars OR matches: architect, design, pattern, refactor, migrate, scalab | Complex |
|
||||
| All other questions | Simple |
|
||||
|
||||
**Complex questions** -> delegate to CLI exploration:
|
||||
|
||||
```bash
|
||||
Bash(command="ccw cli -p \"PURPOSE: Architecture consultation for: <question_summary>
|
||||
TASK: Search codebase for relevant patterns, analyze architectural implications, provide options with trade-offs
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*
|
||||
EXPECTED: Options with trade-offs, file references, architectural implications
|
||||
CONSTRAINTS: Advisory only, provide options not decisions\" --tool gemini --mode analysis --rule analysis-review-architecture", timeout=300000)
|
||||
```
|
||||
|
||||
**Simple questions** -> direct analysis using available context (wisdom, project-tech, codebase search).
|
||||
|
||||
---
|
||||
|
||||
### Mode: feasibility
|
||||
|
||||
Evaluate technical feasibility of a proposal.
|
||||
|
||||
**Assessment areas**:
|
||||
|
||||
| Area | Method | Output |
|
||||
|------|--------|--------|
|
||||
| Tech stack compatibility | Compare proposal needs against project-tech.json | Compatible / Requires additions |
|
||||
| Codebase readiness | Search for integration points using Grep/Glob | Touch-point count |
|
||||
| Effort estimation | Based on touch-point count (see table below) | Low / Medium / High |
|
||||
| Risk assessment | Based on effort + tech compatibility | Risks + mitigations |
|
||||
|
||||
**Effort estimation**:
|
||||
|
||||
| Touch Points | Effort | Implication |
|
||||
|-------------|--------|-------------|
|
||||
| <= 5 | Low | Straightforward implementation |
|
||||
| 6 - 20 | Medium | Moderate refactoring needed |
|
||||
| > 20 | High | Significant refactoring, consider phasing |
|
||||
|
||||
**Verdict for feasibility**:
|
||||
|
||||
| Condition | Verdict |
|
||||
|-----------|---------|
|
||||
| Low/medium effort, compatible stack | FEASIBLE |
|
||||
| High touch-points OR new tech required | RISKY |
|
||||
| Fundamental incompatibility or unreasonable effort | INFEASIBLE |
|
||||
|
||||
---
|
||||
|
||||
### Verdict Routing (all modes except feasibility)
|
||||
|
||||
| Verdict | Criteria |
|
||||
|---------|----------|
|
||||
| BLOCK | >= 2 high-severity concerns |
|
||||
| CONCERN | >= 1 high-severity OR >= 3 medium-severity concerns |
|
||||
| APPROVE | All other cases |
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
### Output Format
|
||||
|
||||
Write assessment to `<session_folder>/architecture/arch-<slug>.json`.
|
||||
|
||||
**Report content sent to coordinator**:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| mode | Consultation mode used |
|
||||
| verdict | APPROVE / CONCERN / BLOCK (or FEASIBLE / RISKY / INFEASIBLE) |
|
||||
| concern_count | Number of concerns by severity |
|
||||
| recommendations | Actionable suggestions with trade-offs |
|
||||
| output_path | Path to full assessment file |
|
||||
|
||||
**Wisdom contribution**: Append significant decisions to `<session_folder>/wisdom/decisions.md`.
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Architecture docs not found | Assess from available context, note limitation in report |
|
||||
| Plan file missing | Report to coordinator via arch_concern |
|
||||
| Git diff fails (no commits) | Use staged changes or skip code-review mode |
|
||||
| CLI exploration timeout | Provide partial assessment, flag as incomplete |
|
||||
| Exploration results unparseable | Fall back to direct analysis without exploration |
|
||||
| Insufficient context | Request explorer assistance via coordinator |
|
||||
Reference in New Issue
Block a user