/architect Workflow

Inputs

• Feature request: $ARGUMENTS
• Flags: --fast skips the red team review (use for low-risk changes)

Step 0 — Pre-flight (optional)

Check for project-specific agents (parallel):

Tool: Glob (direct — coordinator does this)

Run all three globs in parallel:

• Pattern 1: .claude/agents/senior-architect.md
• Pattern 2: .claude/agents/code-reviewer.md
• Pattern 3: .claude/agents/security-analyst.md

If senior-architect found:

• Output: "✅ Using project-specific senior-architect from .claude/agents/"

If senior-architect not found:

• Output note: "💡 No project-specific senior-architect found. Will use generic Task subagent for planning.\n For project-tailored planning, generate one:\n gen-agent . --type senior-architect"
• Continue to Step 1 (do not block).

If code-reviewer found:

• Output: "✅ Using project-specific code-reviewer from .claude/agents/"

If code-reviewer not found:

• Output note: "💡 No project-specific code-reviewer found. Will use generic Task subagent for feasibility checks.\n For project-tailored reviews, generate one:\n gen-agent . --type code-reviewer"

If security-analyst found:

• Output: "✅ Found project-specific security-analyst (available for security-focused plans)"

If security-analyst not found:

• Output note: "💡 No project-specific security-analyst found. Will use generic Task subagent for red team review.\n For project-tailored analysis, generate one:\n gen-agent . --type security-analyst"

• Pattern 4: ~/.claude/skills/threat-model-gate/SKILL.md

If threat-model-gate found:

• Output: "Threat model gate active. Security-related plans will include threat modeling requirements."

If threat-model-gate not found:

• No output (threat-model-gate is optional at all maturity levels).

Continue to Step 1.

Initialize audit logging:

Tool: Bash

# --- Audit Logging Setup ---
RUN_ID=$(date +%Y%m%d-%H%M%S)-$(cat /dev/urandom | LC_ALL=C tr -dc 'a-z0-9' | head -c 6)
AUDIT_LOG_DIR="./plans/audit-logs"
mkdir -p "$AUDIT_LOG_DIR"
AUDIT_LOG="$AUDIT_LOG_DIR/architect-${RUN_ID}.jsonl"
STATE_FILE=".architect-audit-state-${RUN_ID}.json"

python3 -c "
import json
state = {
    'run_id': '${RUN_ID}',
    'audit_log': '${AUDIT_LOG}',
    'skill': 'architect',
    'skill_version': '3.3.0',
    'security_maturity': 'advisory',
    'hmac_key': ''
}
with open('${STATE_FILE}', 'w') as f:
    json.dump(state, f)
print('Architect audit state file created: ${STATE_FILE}')
"

bash scripts/emit-audit-event.sh "$STATE_FILE" \
  "{\"event_type\":\"run_start\",\"plan_feature\":\"${ARGUMENTS:-unknown}\"}"

echo "Architect audit log: $AUDIT_LOG"

Step 1 — Context Discovery

Emit step_start for Step 1:

Tool: Bash

bash scripts/emit-audit-event.sh ".architect-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_start","step":"step_1_context_discovery","step_name":"Context discovery","agent_type":"coordinator"}'

Gather project context to inform the architect. All reads run in parallel (single message with multiple tool calls). This step runs regardless of the --fast flag.

Tool: Glob, Read (direct — coordinator does this)

Parallel reads (single message):

1. Project patterns: Read ./CLAUDE.md (if exists). Extract key sections: architecture, conventions, tech stack, development rules.

2. Recent plans: Glob ./plans/*.md (exclude *.redteam.md, *.review.md, *.feasibility.md, *.code-review.md, *.qa-report.md, *.test-failure.log, *.summary.md, *.hardener.md, *.performance.md, *.qa.md). Sort by modification time (newest first). Read up to 3 most recent plan files.

3. Archived plans: Glob ./plans/archive/*/*.md (exclude *.code-review.md, *.qa-report.md). Sort by modification time (newest first). Read up to 2 most recent archived plan files.

4. Codebase structure: Run codebase scanner to extract structural facts.

Tool: Bash

# Run codebase scanner (degrades gracefully if tree-sitter not installed)
SCANNER_PYTHON="${HOME}/.claude-devkit/scanner-venv/bin/python3"
SCANNER_SCRIPT="${CLAUDE_DEVKIT:-./}/scripts/codebase-scanner.py"
if [ ! -f "$SCANNER_SCRIPT" ]; then
  SCANNER_SCRIPT="./scripts/codebase-scanner.py"
fi
if [ -x "$SCANNER_PYTHON" ]; then
  SCANNER_OUTPUT=$("$SCANNER_PYTHON" "$SCANNER_SCRIPT" --format summary --quiet 2>/dev/null || echo "")
else
  SCANNER_OUTPUT=$(python3 "$SCANNER_SCRIPT" --format summary --quiet 2>/dev/null || echo "")
fi
echo "$SCANNER_OUTPUT"

# Emit scanner_invocation audit event
if [ -n "$SCANNER_OUTPUT" ]; then
  SCANNER_HASH=$(printf '%s' "$SCANNER_OUTPUT" | python3 -c "import sys,hashlib; print(hashlib.sha256(sys.stdin.read().encode()).hexdigest())" 2>/dev/null || echo "unknown")
  SCANNER_VERSION=$(python3 "$SCANNER_SCRIPT" --version 2>/dev/null | awk '{print $NF}' || echo "unknown")
  SCANNER_FILE_COUNT=$(printf '%s' "$SCANNER_OUTPUT" | grep -oP 'Files scanned:\s*\K[0-9]+' 2>/dev/null || echo "unknown")
  SCANNER_SYMBOL_COUNT=$(printf '%s' "$SCANNER_OUTPUT" | grep -oP 'Total symbols:\s*\K[0-9]+' 2>/dev/null || echo "unknown")
  SCANNER_PARSER_MODE=$(printf '%s' "$SCANNER_OUTPUT" | grep -oP 'Parser:\s*\K\S+' 2>/dev/null || echo "unknown")
  bash scripts/emit-audit-event.sh ".architect-audit-state-${RUN_ID}.json" \
    "{\"event_type\":\"scanner_invocation\",\"scanner_version\":\"${SCANNER_VERSION}\",\"parser_mode\":\"${SCANNER_PARSER_MODE}\",\"file_count\":\"${SCANNER_FILE_COUNT}\",\"symbol_count\":\"${SCANNER_SYMBOL_COUNT}\",\"output_sha256\":\"${SCANNER_HASH}\"}"
fi

Construct $CONTEXT_BLOCK:

Assemble the discovered context into a structured block:

---begin context block format---

Discovered Project Context

Project Patterns (from CLAUDE.md)

[Key architecture, conventions, tech stack, and development rules extracted from CLAUDE.md] [If CLAUDE.md not found: "No CLAUDE.md found. Architect should establish project patterns."]

Recent Plans

[For each of up to 3 recent plans: filename, title/goal line, status (APPROVED or not)] [If no plans found: "No prior plans found. This appears to be the first planned feature."]

Historical Plans (Archived)

[For each of up to 2 archived plans: filename, title/goal line] [If no archived plans found: "No archived plans found."]

Codebase Structure (auto-generated)

[Scanner output from step 4, or "Scanner not available. Agent will discover structure during planning."] ---end context block format---

If CLAUDE.md does not exist: Set patterns section to "No CLAUDE.md found." Continue to Step 2 (do not block).

If no plans exist: Set plans sections to "No prior plans found." Continue to Step 2 (do not block).

Emit step_end for Step 1:

Tool: Bash

bash scripts/emit-audit-event.sh ".architect-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_end","step":"step_1_context_discovery","step_name":"Context discovery","agent_type":"coordinator"}'

Continue to Step 2.

Step 2 — Architect drafts plan

Emit step_start for Step 2:

Tool: Bash

bash scripts/emit-audit-event.sh ".architect-audit-state-${RUN_ID}.json" \
  '{"event_type":"step_start","step":"step_2_architect_draft","step_name":"Architect drafts plan","agent_type":"architect"}'

Invoke the project-level architect. If none found, use a Task subagent with general-purpose prompt.

IMPORTANT: When calling the Task tool, you MUST pass the exact model string claude-opus-4-6 — do NOT use shorthand like opus which resolves to a different model.

Tool: Task, subagent_type=general-purpose, model=claude-opus-4-6

Prompt: "Analyze the codebase and draft a Technical Implementation Plan for: $ARGUMENTS.

Project Context (from Step 1 discovery):

$CONTEXT_BLOCK

Use this context to:

• Align with existing project patterns and conventions from CLAUDE.md
• Avoid duplicating or conflicting with prior plans
• Reference relevant historical decisions where applicable
• Foll