v3.3.0: Agent Reasoning Upgrade — Values + Domain Lens

Agent Reasoning Upgrade

Production-validated improvement from 6 weeks of real-world usage. Replaces free-form agent philosophy prose with structured reasoning that improved finding extraction rate from 9.5% to ~16.2%.

The Problem

All 12 specialist agents had "Specialist Philosophy" sections -- free-form prose describing their beliefs. In practice, agents skipped these paragraphs and jumped to checklist execution. The philosophy affected tone but not reasoning procedure.

The Fix

Replace ## Specialist Philosophy with two structured sections in all 12 agent definitions:

• ## Values (2-3 sentences) -- Load-bearing beliefs that shape judgment in edge cases. Only sentences that introduce a value or tension between values survive; illustration and narrative are cut.

• ## Domain Lens (5 steps) -- Structured reasoning sequence applied before analysis begins. The procedural scaffold that ensures minimum domain coverage.

Additional Changes

• 8 specialist output formats: Added Rule and Exceptions fields to findings (enables deduplication and pattern mining)
• Facilitator dispatch: Added Domain Reframe instruction -- one sentence connecting the change to the specialist's domain
• Facilitator synthesis: Switched to delta format with location-aware deduplication
• Review command: Dispatch template includes Domain Reframe + Domain Lens activation
• ADR-0010: Documents the structural change with source evidence

Why Values + Domain Lens Work Together

Approach	Limitation
Domain Lens alone	Caps agents at Bloom's Apply -- they follow procedures but miss proportionality judgments
Values alone (old philosophy)	Gets skipped -- prose that is not procedural does not change agent behavior
Values + Domain Lens	Domain Lens guarantees coverage; Values provide judgment that elevates beyond checklists

Example: Security Specialist

Values: Security calibrated to the actual threat model is more valuable than theoretical perfection. A single-user local app and a public SaaS have fundamentally different threat surfaces.

Domain Lens:

1. Identify the threat model: actors, attack surface, value of what is inside
2. Map trust boundaries
3. Walk OWASP Top-10 against each boundary-crossing code path
4. For each finding, specify attack vector and blast radius
5. Calibrate severity to actual deployment context

Framework Scale (v3.3)

Component	Count
Agents (all with Values + Domain Lens)	12 (4 Opus, 8 Sonnet)
Slash commands	18
Auto-loaded rules	12
Hooks	7
Skills	6
ADRs	10

Upgrade Path from v3.2

1. Replace ## Specialist Philosophy with ## Values + ## Domain Lens in all agent definitions
2. Add Rule and Exceptions fields to specialist finding output formats
3. Update facilitator dispatch template with Domain Reframe
4. Update CLAUDE.md terminology

Review

Reviewed as REV-20260404-070200 with architecture-consultant, docs-knowledge, and independent-perspective. 3 blocking findings resolved. See ADR-0010 for full decision record.

v0.1.0 — Initial Framework Release

AI-Native Agentic Development Framework for Claude Code.

What's included

• 11 specialist agents (architecture, security, QA, performance, docs, UX, and more)
• 16 slash commands (/plan, /build_module, /review, /deliberate, /ship, etc.)
• Structured multi-agent code review with risk-tiered specialist panels
• Mid-build checkpoint reviews enforcing independent evaluation
• Four-layer capture stack (immutable logs → SQLite → curated memory)
• Automated quality gates (formatting, linting, tests, coverage)
• Education gates (walkthrough → quiz → explain-back → merge)
• Framework lineage tracking for derived projects

Getting started

Clone the template and follow the Quick Start in the README.