Claude-Code-Workflow/.claude/skills/team-lifecycle-v4/roles/architect/commands/assess.md

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(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(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