docs: add agent-design convention pack (AD-001 through AD-010)

[jflowers]

Summary

Adds the agent-design convention pack (.opencode/uf/packs/agent-design.md) with 10 structural quality rules (AD-001 through AD-010) that give AI coding agents explicit architectural constraints. This addresses issue #4.

The pack covers:

• Coupling (vibe-check): Package fan-out Ce < 10 (AD-002), Instability I < 0.7 for non-leaf packages (AD-003), no circular dependencies (AD-004)
• Cohesion/Duplication (vibe-check): No duplicated blocks >= 6 lines (AD-008), LCOM4 <= 3 (AD-009)
• Complexity/Coverage (gaze): Cognitive complexity < 15 (AD-001), contract coverage for all exports (AD-006), >= 1 behavioral assertion per test (AD-010)
• Naming/Structure: Go naming conventions via golangci-lint revive (AD-005), file size < 400 lines (AD-007)

Forward references to planned features (--max-ce, --max-duplication) are explicitly marked with heuristic enforcement fallbacks.

How to Test

1. Verify all 10 rules are present with required fields:

   grep -c '### AD-' .opencode/uf/packs/agent-design.md
   # Expected: 10

2. Verify vibe-check enforcement references (AD-002, AD-003, AD-004, AD-008, AD-009):

   grep 'vibe-check' .opencode/uf/packs/agent-design.md

3. Verify gaze enforcement references (AD-001, AD-006, AD-010):

   grep 'gaze' .opencode/uf/packs/agent-design.md

4. Verify AGENTS.md includes the new packs:

   grep 'agent-design' AGENTS.md

5. Verify each rule has all required fields (Severity, Rationale, Threshold, Enforcement, Example with pass/fail):

   grep -c '^\*\*Severity\*\*' .opencode/uf/packs/agent-design.md    # 10
   grep -c '^\*\*Rationale\*\*' .opencode/uf/packs/agent-design.md   # 10
   grep -c '^\*\*Threshold\*\*' .opencode/uf/packs/agent-design.md   # 10
   grep -c '^\*\*Enforcement\*\*' .opencode/uf/packs/agent-design.md # 10
   grep -c '^\*\*Example\*\*' .opencode/uf/packs/agent-design.md     # 10

How to Demo

1. Open .opencode/uf/packs/agent-design.md and review the 10 rules organized by enforcement category
2. Open .opencode/uf/packs/agent-design-custom.md to see the project-level override placeholder with CR-NNN convention
3. Check AGENTS.md Convention Packs section to confirm both files are listed

Key Files Changed

Convention Pack (new)

• .opencode/uf/packs/agent-design.md — Main pack with 10 structural quality rules (+236 lines)
• .opencode/uf/packs/agent-design-custom.md — Override placeholder (+25 lines)

Documentation (modified)

• AGENTS.md — Added both pack files to Convention Packs list (+2 lines)
• CHANGELOG.md — Added unreleased entry for the new pack (+6 lines)

OpenSpec Artifacts (new)

• openspec/changes/agent-design-pack/proposal.md — Change proposal (+72 lines)
• openspec/changes/agent-design-pack/design.md — Design decisions (+111 lines)
• openspec/changes/agent-design-pack/specs/agent-design-rules/spec.md — 12 requirements with scenarios (+199 lines)
• openspec/changes/agent-design-pack/tasks.md — 16 tasks, all complete (+40 lines)

Dewey Learnings (new)

• .uf/dewey/learnings/ — 4 session learnings (convention pack authoring, LCOM4 semantics, spec review patterns)

Known Issues

The following findings from the review council were acknowledged but not resolved:

• MEDIUM: Rule IDs are non-sequential within sections (AD-002/003/004, then AD-008/009, then AD-001/006/010, then AD-005/007) due to grouping by enforcement tool rather than by ID number. This is intentional per the design doc (D2) and matches the spec.
• MEDIUM: CHANGELOG entry missing Spec: path to canonical spec. This is a project-wide gap (no existing CHANGELOG entries include Spec: paths), not a regression.

This PR was generated by /uf.finale (AI-assisted).

[jflowers]

Note: Could not post as APPROVE due to GitHub's self-review prohibition (PR author cannot approve their own PR). Posted as COMMENT instead. Original verdict: APPROVE.

Council Verdict: APPROVE

Reviewers: adversary, architect, curator, entropy, envoy, guard, herald, scribe, sre, testing
Iterations: 2 (initial review + 1 fix cycle)

Adversary (APPROVE)

4 LOW findings omitted.

Architect (APPROVE)

• [MEDIUM] Convention pack section headings deviate from established template (justified by D2 design decision — cross-cutting pack doesn't fit standard sections)
• [MEDIUM] Rule ID format differs from established convention (justified by D2 — richer format needed for threshold/enforcement mappings)

3 LOW findings omitted.

Curator (APPROVE)

• [MEDIUM] Convention pack lacks a summary table for quick agent scanning
• [HIGH] Missing documentation issue — resolved: filed as #29

2 LOW findings omitted.

Entropy (APPROVE)

4 LOW findings omitted.

Envoy (APPROVE — was REQUEST CHANGES)

All findings resolved in iteration 1:

• [MEDIUM] proposal.md AD-009 misclassification — fixed

3 LOW findings omitted.

Guard (APPROVE)

2 LOW findings omitted.

Herald (APPROVE)

5 LOW findings omitted.

Scribe (APPROVE — was REQUEST CHANGES)

All findings resolved in iteration 1:

• [HIGH] AD-003 leaf-exemption not enforced by CLI — fixed (enforcement clarification added)

2 LOW findings omitted.

SRE (APPROVE)

3 LOW findings omitted.

Testing (APPROVE)

6 LOW findings omitted.

Fixes Applied (Iteration 1)

1. proposal.md: Removed AD-009 from forward-planned list
2. agent-design.md: Clarified AD-003 leaf exemption is agent-enforced, not CLI-enforced
3. spec.md: Fixed bare vibe-check → vibe-check analyze for AD-008
4. tasks.md: Fixed 3 bare vibe-check invocations to include analyze subcommand
5. design.md: Split forward-reference risk bullet; added leaf-package exemption documentation

---

This review was generated by /review-council (AI-assisted).

[jflowers]

PR Cost Report: #28

Session: Change proposal workflow

ID: ses_fa1612921ffeNeXbTOGmv76rxp
Model: claude-opus-4-6

Metric	Value
Cost (parent only)	$12.74
Input tokens	159
Output tokens	66,811
Cache read tokens	11,127,020
Cache write tokens	880,599

Timeline: 2026-09-01 16:17:43 — 2026-09-01 17:37:18

Child sessions: 9 — additional cost: $6.93
Session tree total: $19.67

Child session breakdown

Session	Model	Cost	Output Tokens
Spec review - Adversary (@divisor-adversary subagent)	claude-opus-4-6	$0.76	6,402
Spec review - Architect (@divisor-architect subagent)	claude-opus-4-6	$0.91	5,346
Spec review - Guard (@divisor-guard subagent)	claude-opus-4-6	$0.68	4,971
Adversary spec re-review R2 (@divisor-adversary subagent)	claude-opus-4-6	$0.52	3,723
Architect spec re-review R2 (@divisor-architect subagent)	claude-opus-4-6	$0.96	5,035
Guard spec re-review R2 (@divisor-guard subagent)	claude-opus-4-6	$0.66	4,151
Adversary code review (@divisor-adversary subagent)	claude-opus-4-6	$0.75	3,012
Architect code review (@divisor-architect subagent)	claude-opus-4-6	$0.86	4,391
Guard code review (@divisor-guard subagent)	claude-opus-4-6	$0.83	4,638

---

Session: Code and spec review council

ID: ses_fa1181e5dffednMcuj9hl3TzDM
Model: claude-opus-4-6

Metric	Value
Cost (parent only)	$5.75
Input tokens	58
Output tokens	30,634
Cache read tokens	3,661,005
Cache write tokens	504,218

Timeline: 2026-09-01 17:37:30 — 2026-09-02 08:34:51

Child sessions: 12 — additional cost: $9.13
Session tree total: $14.87

Child session breakdown

Session	Model	Cost	Output Tokens
Adversary review - agent design pack (@divisor-adversary subagent)	claude-opus-4-6	$0.74	4,358
Architect review - agent design pack (@divisor-architect subagent)	claude-opus-4-6	$1.04	5,543
Guard review - agent design pack (@divisor-guard subagent)	claude-opus-4-6	$0.98	5,519
Testing review - agent design pack (@divisor-testing subagent)	claude-opus-4-6	$0.71	4,553
SRE review - agent design pack (@divisor-sre subagent)	claude-opus-4-6	$0.88	4,374
Curator review - agent design pack (@divisor-curator subagent)	claude-opus-4-6	$0.82	6,447
Entropy review - agent design pack (@general subagent)	claude-sonnet-4-6	$0.43	4,109
Envoy review - agent design pack (@general subagent)	claude-sonnet-4-6	$0.80	9,979
Herald review - agent design pack (@general subagent)	claude-sonnet-4-6	$0.56	7,253
Scribe review - agent design pack (@general subagent)	claude-sonnet-4-6	$1.50	14,418
Envoy re-review (iteration 1) (@divisor-envoy subagent)	claude-opus-4-6	$0.33	1,522
Scribe re-review (iteration 1) (@divisor-scribe subagent)	claude-opus-4-6	$0.33	1,537

---

Grand Total: $34.54 across 2 session tree(s) (23 sessions)