Agentic Persona Team

01Overview

Dev Team is a Claude Code plugin that gives you a multi-agent team for building software. You describe what you want to build, and specialists in security, accessibility, architecture, performance, and 16 other domains analyze, review, and build it — each bringing structured expertise from the agentic-cookbook.

The system works through three repos: the cookbook holds principles and guidelines, dev-team (this plugin) provides the agents and orchestration, and your workspace repo stores the project data.

20Specialists

231Specialty Teams

20Agents

8Commands

136Contract Tests

02Commands

Single entry point: /dev-team <command>. Each command is a workflow run by a team-lead.

Command	Lead	What It Does
/dev-team interview	interview	Discover product requirements through structured and exploratory questioning with specialist expertise
/dev-team create-recipe-from-code	analysis	Reverse-engineer a codebase into a cookbook project
/dev-team generate	review	Improve a cookbook project through specialist review
/dev-team create-code-from-recipe	build	Build working code from a cookbook project
/dev-team lint	audit	Evaluate any file against cookbook standards
/dev-team align-specialists	audit	Review specialist-cookbook alignment after guideline changes
/dev-team compare-code	analysis	Compare two code projects for round-trip verification
/dev-team view-recipe	—	Generate HTML view of a cookbook project (read-only)

03Pipeline

How a workflow runs end-to-end. The team-lead is the only component that talks to the user. All other communication flows through the arbitrator.

System Architecture

Participant Roles

Session Lifecycle

Team-Leads 5 types

Each team-lead type runs a specific category of workflow and has its own persona.

Type	Workflows
interview	Product discovery and requirements gathering
analysis	Codebase analysis, project creation, code comparison
review	Specialist review and recipe improvement
build	Code generation from cookbook projects
audit	Linting, alignment checking

Interaction Contract — 5 Message Types communication

Type	Direction	Description
Question	Lead → User	Open-ended, needs thoughtful answer
Answer	User → Lead	Response to a question
Gate	Lead → User	Options presented, work pauses until verdict
Verdict	User → Lead	Selected option from a gate
Notification	Lead → User	One-way status update, no response needed

Gate Categories

flow — normal checkpoint (assignment approval, suggestion approve/reject). error — something broke (retry, skip, abort). conflict — specialists disagree (pick a direction).

Notification Attributes

Severity: info, warning, error. Category: progress, result, briefing.

04Specialists

20 specialists, each with a role, persona, cookbook sources, and a manifest of specialty-teams. Each specialty-team is a worker-verifier pair focused on one cookbook guideline, principle, or compliance check.

Domain Specialists (13) domain

Specialist	Focus
accessibility	WCAG compliance, screen readers, keyboard navigation, color contrast
claude-code	Agentic development, Claude Code patterns, performance
code-quality	Simplicity, deletability, explicitness, linting, atomic commits
data-persistence	Storage, caching, migration, sync, offline-first
development-process	Git workflow, CI/CD, code review, documentation
devops-observability	Logging, metrics, tracing, alerting, deployment
localization-i18n	Internationalization, locale handling, RTL, pluralization
networking-api	REST design, error handling, pagination, authentication
reliability	Error handling, retry logic, circuit breakers, graceful degradation
security	Auth, transport, tokens, input validation, CORS, CSP, privacy
software-architecture	Modularity, dependency management, patterns, boundaries
testing-qa	Unit tests, integration tests, coverage, test design
ui-ux-design	Layout, typography, color, interaction, responsive design

Platform Specialists (6) platform

Specialist	Focus
platform-android	Android SDK, Kotlin, Jetpack Compose, lifecycle
platform-database	Schema design, sync architecture, indexing, query optimization, transactions, backup/recovery (22 teams + 3 consulting)
platform-ios-apple	Swift, SwiftUI, UIKit, Apple frameworks
platform-web-backend	Python, Node.js, API servers, middleware
platform-web-frontend	React, TypeScript, CSS, bundling, SSR
platform-windows	WinUI, .NET, MSIX, Windows APIs

Project Management (1) pm

Specialist	Focus
project-manager	Schedules, todos, issues, concerns, dependencies, decisions

Manages dev-team-project data through the project-storage-provider. Has 6 specialty-teams: schedule, todos, issues, concerns, dependencies, decisions.

05Specialty-Teams

231 standalone files across 20 categories. Each defines a worker-verifier pair focused on one cookbook guideline, principle, or compliance check. The atomic unit of specialist expertise.

Specialist dispatches Specialty-Team→ Worker reads cookbook guideline, produces findings→ Verifier checks worker output→ PASS → findings recorded→ FAIL → retry (max 3) → escalate

Isolation principle: Worker and verifier never see each other's instructions. This is a checks-and-balances design — the verifier can't be biased by the worker's approach.

accessibility (2) domain

Team	Description	Cookbook Source
accessibility-compliance	8 compliance checks — screen-reader-support, keyboard-navigable, dynamic-type-support, contrast-ratio, touch-target-size	compliance/accessibility.md
accessibility	Semantic roles and labels on all interactive elements; full screen reader support (VoiceOver, TalkBack, Narrator, ARIA);	guidelines/accessibility/accessibility.md

claude-code (15) domain

Team	Description	Cookbook Source
agent-checklist	Structure checks (frontmatter present with name+description, kebab-case filename); content quality (single responsibilit	guidelines/skills-and-agents/agent-checklist.md
agent-structure-reference	Agents are `.md` files in `.claude/agents/` with YAML frontmatter; body is the system prompt; frontmatter fields (name,	guidelines/skills-and-agents/agent-structure-reference.md
authoring-skills-and-rules	Skill design rules — check inventory first, version from day one, session version check, use `$ARGUMENTS` and `${CLAUDE_	guidelines/skills-and-agents/authoring-skills-and-rules.md
design-for-deletion	Build skills and rules that are easy to remove without affecting others; treat lines of instructions as lines spent — de	principles/design-for-deletion.md
explicit-over-implicit	Make dependencies visible — skills that need files should read them explicitly, not rely on ambient context; name things	principles/explicit-over-implicit.md
manage-complexity-through-boundaries	Well-defined interfaces between subsystems — skills expose clear input/output contracts; agents receive narrow, specific	principles/manage-complexity-through-boundaries.md
performance	Three principles — (1) shell scripts for deterministic work (scaffolding, git, build, lint, file manipulation, metrics);	guidelines/skills-and-agents/performance.md
rule-checklist	Content quality (single responsibility, actionable/specific, no conflicting instructions); rule-specific (imperative ton	guidelines/skills-and-agents/rule-checklist.md
rule-structure-reference	Rules are plain `.md` files (no required frontmatter schema), lowercase kebab-case filename, per-turn cost model (rules	guidelines/skills-and-agents/rule-structure-reference.md
separation-of-concerns	Each skill, rule, and agent should have one reason to change; if describing what a skill/rule does requires "and," consi	principles/separation-of-concerns.md
simplicity	Simple means no interleaving of concerns — not just "familiar"; optimizing for easy (convenient) leads to complexity tha	principles/simplicity.md
skill-checklist	Structure checks (frontmatter present, name kebab-case ≤64 chars, description present, main file named `SKILL.md`, ≤500	guidelines/skills-and-agents/skill-checklist.md
skill-structure-reference	Directory layout (`.claude/skills/<name>/SKILL.md` + optional references/scripts/examples/); frontmatter fields (name, d	guidelines/skills-and-agents/skill-structure-reference.md
support-automation	Skills and agents should expose capabilities through scriptable interfaces — not just interactive use; design operations	principles/support-automation.md
yagni	Build skills and agents for today's known requirements; speculative generality in prompts (adding "in case we need it" c	principles/yagni.md

code-quality (8) domain

Team	Description	Cookbook Source
atomic-commits	One logical change per commit; follow build-verify-commit loop (change → build → verify → commit → repeat); never stack	guidelines/code-quality/atomic-commits.md
best-practices-compliance	8 compliance checks — unit-test-coverage, test-pyramid, atomic-commits, code-linting, post-generation-verification, expl	compliance/best-practices.md
bulk-operation-verification	After any operation touching 5+ files, run a verification pass; grep entire repo for stale references (old names, paths,	guidelines/code-quality/bulk-operation-verification.md
design-for-deletion	Treat every line of code as a maintenance liability; build disposable units that can be thrown away without affecting th	principles/design-for-deletion.md
explicit-over-implicit	Make dependencies visible via injection rather than hidden globals; name things for what they do; prefer explicit parame	principles/explicit-over-implicit.md
linting	Linting configured from day one on every project; linter config committed to repo; linting runs as part of build or pre-	guidelines/code-quality/linting.md
scope-discipline	Only modify what was requested; state the goal before starting; note but do not fix adjacent issues; recognize scope cre	guidelines/code-quality/scope-discipline.md
simplicity	Distinguish simple (no interleaving of concerns) from easy (convenient); resist adding abstractions that braid two conce	principles/simplicity.md

data-persistence (4) domain

Team	Description	Cookbook Source
idempotency	User actions and system operations safe to repeat without duplicate side effects; buttons debounced or disabled during a	principles/idempotency.md
immutability	Mutable shared state eliminated as the root cause of concurrency bugs; `let`/`val`/`const` used by default; value types	principles/immutability-by-default.md
offline-and-connectivity	Local-first design with background sync; optimistic updates with rollback on server failure; queue-based outbox for muta	guidelines/networking/offline-and-connectivity.md
reliability-compliance	8 compliance checks — error-recovery, graceful-degradation, fault-tolerance, state-recovery, idempotent-operations, time	compliance/reliability.md

development-process (6) domain

Team	Description	Cookbook Source
ab-testing	Features that may need experimentation support variant assignment via `ExperimentProvider` interface (`variant(key) -> S	guidelines/feature-management/ab-testing.md
debug-mode	Debug-only configuration panel not included in release builds — contains feature flag overrides, analytics event log, A/	guidelines/feature-management/debug-mode.md
feature-flags	All features gated behind feature flags from initial implementation; `FeatureFlagProvider` interface (`isEnabled(key) ->	guidelines/feature-management/feature-flags.md
make-it-work	Sequential phases — correctness first (common case working), then refactor for clarity and edge cases, then optimize onl	principles/make-it-work-make-it-right-make-it-fast.md
small-reversible-decisions	Fast decisions on cheap-to-reverse choices; invest in understanding before committing to expensive-to-reverse decisions;	principles/small-reversible-decisions.md
yagni	Build only for today's known requirements; no speculative abstractions, hooks for future features, or generalization bey	principles/yagni.md

devops-observability (7) domain

Team	Description	Cookbook Source
ab-testing	Features that may need experimentation support variant assignment via `ExperimentProvider` interface (`variant(key) -> S	guidelines/feature-management/ab-testing.md
analytics	All significant user actions instrumented via an `AnalyticsProvider` interface (`track(event, properties)`); no direct c	guidelines/logging/analytics.md
debug-mode	Debug-only configuration panel (not in release builds) with feature flag overrides, analytics event log, A/B test varian	guidelines/feature-management/debug-mode.md
feature-flags	All features gated behind feature flags from initial implementation; `FeatureFlagProvider` interface (`isEnabled(key) ->	guidelines/feature-management/feature-flags.md
logging	Every component and flow instrumented with structured logging using platform best-in-class framework (os.log/Logger on A	guidelines/logging/logging.md
performance-compliance	8 compliance checks — main-thread-freedom, animation-frame-rate (60fps/16ms), lazy-loading, resource-efficiency, startup	compliance/performance.md
tight-feedback-loops	Optimize test suite runtime so tests actually get run; deploy small changes frequently; get real user feedback early; au	principles/tight-feedback-loops.md

localization-i18n (3) domain

Team	Description	Cookbook Source
internationalization-compliance	7 compliance checks — string-externalization, rtl-layout-support, locale-aware-formatting, plural-forms, text-expansion-	compliance/internationalization.md
localization	All user-facing strings externalized into platform-standard resource files — `.xcstrings`/`.strings` (Swift), `strings.x	guidelines/internationalization/localization.md
rtl-support	Leading/trailing (not left/right) for all alignment and padding; directional icons mirrored; non-directional icons not m	guidelines/internationalization/rtl-support.md

networking-api (11) domain

Team	Description	Cookbook Source
access-patterns-compliance	8 compliance checks — api-design-conventions, offline-behavior, retry-with-backoff, timeout-configuration, rate-limit-ha	compliance/access-patterns.md
api-design	REST with consistent URL conventions (lowercase-hyphen, plural nouns, max 2 nesting levels, no verbs, no trailing slashe	guidelines/networking/api-design.md
caching	Server controls cache policy via headers; immutable versioned assets use `public, max-age=31536000, immutable`; dynamic	guidelines/networking/caching.md
error-responses	RFC 9457 Problem Details format with `Content-Type: application/problem+json`; required fields: `type` (URI), `title` (s	guidelines/networking/error-responses.md
offline-and-connectivity	Local-first with background sync for offline apps; three patterns in complexity order — optimistic updates (rollback on	guidelines/networking/offline-and-connectivity.md
pagination	Cursor pagination preferred for most APIs — stable under concurrent mutations, consistent performance at any depth; offs	guidelines/networking/pagination.md
principle-of-least-astonishment	API and system behavior must match what callers expect; names must deliver exactly what they suggest; side effects must	principles/principle-of-least-astonishment.md
rate-limiting	Honor `Retry-After` header on 429 responses; if no `Retry-After`, use exponential backoff; track `RateLimit-Remaining` p	guidelines/networking/rate-limiting.md
real-time-communication	Start with SSE for server-push (built-in reconnection, standard HTTP, sufficient for 80%+ of real-time needs); WebSocket	guidelines/networking/real-time-communication.md
retry-and-resilience	Exponential backoff with full jitter (`random(0, min(max_delay, base * 2^attempt))`); base 1s, max cap 30s, 3-5 retries	guidelines/networking/retry-and-resilience.md
timeouts	Always set both connection timeout (10s) and read/response timeout (30s); total/request timeout 60-120s including retrie	guidelines/networking/timeouts.md

platform-android (11) platform

Team	Description	Cookbook Source
background-tasks	Use `WorkManager` for all deferrable background work — handles constraints, retries, and chaining; use `ForegroundServic	guidelines/platform/background-tasks.md
deep-linking	Android App Links (verified HTTP deep links) via `<intent-filter>` with `autoVerify="true"`; Jetpack Navigation componen	guidelines/platform/deep-linking.md
font-scaling	Layouts must not break at 2x font size; check `Configuration.fontScale` and test with large font settings enabled; use s	guidelines/language/kotlin/font-scaling.md
handoff-and-continuity	Use Firebase Dynamic Links or deep links that resolve in both native and web contexts for Android-to-web continuity; use	guidelines/platform/handoff-and-continuity.md
native-controls	Use platform built-in frameworks before custom implementations; WorkManager over raw thread scheduling; Room over raw SQ	principles/native-controls.md
notifications	Use `NotificationCompat.Builder` for backward-compatible notifications; declare `NotificationChannel` so users control c	guidelines/platform/notifications.md
platform-compliance	7 compliance checks — platform-design-language (Material Design 3), native-controls-preference, platform-touch-targets (	compliance/platform-compliance.md
search-integration	Use Firebase App Indexing or `AppIndexingApi` for on-device search integration; declare searchable content in `searchabl	guidelines/platform/search-integration.md
share-and-inter-app-data	Declare `<intent-filter>` with `ACTION_SEND` and appropriate MIME types to receive shared content; use `Intent.createCho	guidelines/platform/share-and-inter-app-data.md
shortcuts-and-automation	Use `AppActions` for Google Assistant integration; support `Intent`-based automation; expose key app actions as App Acti	guidelines/platform/shortcuts-and-automation.md
widgets-and-glanceable-surfaces	Use Jetpack Glance with Compose-style APIs for home screen widgets; define widget metadata in `appwidget-provider` XML;	guidelines/platform/widgets-and-glanceable-surfaces.md

platform-database (22 + 3 consulting) platform

The most complex specialist. 22 specialty-teams organized across schema design, performance, operations, and sync — plus 3 consulting-teams as cross-cutting verification gates.

Team	Description	Cookbook Source
SCHEMA DESIGN (9)
naming-conventions	snake_case identifiers, PK/FK naming (table_name_id not bare id), reserved word avoidance, index/constraint naming	guidelines/database-design/naming-conventions.md
data-types	SQLite type affinity, STRICT tables, the STRING gotcha, cross-database type mapping (SQLite ↔ PostgreSQL)	guidelines/database-design/data-types.md
primary-keys	INTEGER PRIMARY KEY, AUTOINCREMENT tradeoffs, UUID strategies (v4 vs v7, TEXT vs BLOB), WITHOUT ROWID	guidelines/database-design/primary-keys.md
foreign-keys	PRAGMA foreign_keys = ON, ON DELETE/UPDATE actions, deferred constraints, FK column indexing	guidelines/database-design/foreign-keys.md
constraints-and-validation	CHECK constraints, enum-like constraints, boolean enforcement, range/pattern validation, NULL truthiness	guidelines/database-design/constraints-and-validation.md
relationships	One-to-many, many-to-many join tables, polymorphic FK patterns, self-referential, tree hierarchies	guidelines/database-design/relationships.md
normalization-and-denormalization	3NF starting point, selective denormalization for measured hotspots, sync impact of denormalization	guidelines/database-design/normalization-and-denormalization.md
json-columns	JSON in TEXT columns, extraction operators, generated columns for B-tree indexing, when JSON is a schema smell	guidelines/database-design/json-columns.md
schema-evolution	Migration strategies (user_version pragma), ALTER TABLE limitations, backwards-compatible and sync-compatible migrations	guidelines/database-design/schema-evolution.md
PERFORMANCE (4)
indexing	B-tree fundamentals, partial/expression indexes, composite ordering, covering indexes, EXPLAIN QUERY PLAN	guidelines/database-design/indexing.md
query-optimization	SQLite query planner, rewriting slow queries, avoiding full table scans, JSON query performance, CTEs vs subqueries	guidelines/database-design/query-optimization.md
transactions-and-concurrency	WAL mode, BEGIN IMMEDIATE vs DEFERRED, single writer + multiple readers, busy_timeout, PRAGMA tuning	guidelines/database-design/transactions-and-concurrency.md
access-pattern-analysis	Query pattern analysis, read/write tradeoffs, WHERE/JOIN/ORDER BY design, batch sizing for sync	guidelines/database-design/access-pattern-analysis.md
OPERATIONS (2)
backup-and-recovery	SQLite backup API, Litestream WAL streaming, corruption detection, VACUUM strategy, tombstone purging	guidelines/database-design/backup-and-recovery.md
testing	In-memory vs file-based tests, migration testing, sync logic testing, conflict resolution testing	guidelines/database-design/testing.md
SYNC (7)
sync-schema-design	Dual schema (SQLite + PostgreSQL), UUID PKs for offline creation, soft deletes, dirty tracking, sync metadata	guidelines/database-design/sync-schema-design.md
conflict-resolution	Last-Write-Wins, field-level merge, CRDTs, conflict queues, choosing strategy per data type	guidelines/database-design/conflict-resolution.md
sync-protocol	Push/pull/bidirectional sync, incremental delta sync, change tracking, UPSERT idempotency, outbox pattern	guidelines/database-design/sync-protocol.md
clock-systems	Physical clocks, Lamport timestamps, vector clocks, Hybrid Logical Clocks, server-assigned monotonic versions	guidelines/database-design/clock-systems.md
offline-first-architecture	WAL as offline foundation, operation queue pattern, optimistic UI, rollback on rejection, connectivity-aware sync	guidelines/database-design/offline-first-architecture.md
sync-engine-design	Orchestrator layers, Syncable interface, sync cycle, scheduling, snapshot rebuilding, circuit breakers	guidelines/database-design/sync-engine-design.md
sync-tooling	SQLite Session Extension, cr-sqlite, Litestream, ElectricSQL, PowerSync, Turso/libSQL, sqlite-sync evaluation	guidelines/database-design/sync-tooling.md
CONSULTING TEAMS (3)
cross-database-compatibility	Verifies every schema decision works on both SQLite and PostgreSQL — type mappings, PK strategies, constraints	consulting gate
sync-impact	Catches non-sync team decisions that would break sync, create merge conflicts, or hinder offline operation	consulting gate
access-pattern-coherence	Ensures structural decisions serve actual query patterns — catches schemas that look correct but perform poorly	consulting gate

platform-ios-apple (12) platform

Team	Description	Cookbook Source
background-tasks	Use `BGAppRefreshTask` and `BGProcessingTask` via BackgroundTasks framework for deferred work; use `URLSession` backgrou	guidelines/platform/background-tasks.md
deep-linking	Universal Links for HTTP-based deep links with associated domain entitlement; custom URL schemes as fallback; `onOpenURL	guidelines/platform/deep-linking.md
dynamic-type	Layouts must not break at larger text sizes; use Dynamic Type throughout with no fixed font sizes; custom fonts must res	guidelines/language/swift/dynamic-type.md
handoff-and-continuity	Use `NSUserActivity` to advertise current activity with `isEligibleForHandoff = true`; populate `userInfo` with minimal	guidelines/platform/handoff-and-continuity.md
native-controls	Use platform built-in frameworks before custom implementations; Swift Concurrency over raw threads; SwiftData/Core Data	principles/native-controls.md
notifications	Use `UNUserNotificationCenter` for local and push notifications; permission requested at moment of relevance, not at lau	guidelines/platform/notifications.md
platform-compliance	7 compliance checks — platform-design-language (HIG), native-controls-preference, platform-touch-targets (44pt minimum),	compliance/platform-compliance.md
prefer-explicit-apple-apis	Use UIKit for all iOS UI (UICollectionViewCompositionalLayout, UINavigationController, UITextView, gesture recognizers);	guidelines/language/swift/prefer-explicit-apple-apis.md
search-integration	Use Core Spotlight (`CSSearchableItem`, `CSSearchableItemAttributeSet`) to index content; on iOS 17+ use `IndexedEntity`	guidelines/platform/search-integration.md
share-and-inter-app-data	Use `UIActivityViewController` (iOS) or `NSSharingServicePicker` (macOS) to share content; create Share Extensions to re	guidelines/platform/share-and-inter-app-data.md
shortcuts-and-automation	Use `AppIntents` framework for Shortcuts and Siri integration on iOS and macOS; on macOS support AppleScript via `NSScri	guidelines/platform/shortcuts-and-automation.md
widgets-and-glanceable-surfaces	Use WidgetKit with SwiftUI views (one of the mandated SwiftUI surfaces); support small, medium, and large families; on i	guidelines/platform/widgets-and-glanceable-surfaces.md

platform-web-backend (24) platform

Team	Description	Cookbook Source
access-patterns-compliance	8 compliance checks — api-design-conventions, offline-behavior, retry-with-backoff, timeout-configuration, rate-limit-ha	compliance/access-patterns.md
api-design	REST conventions — lowercase-hyphenated plural-noun URLs, max 2-level nesting, no verbs in URLs, correct HTTP methods wi	guidelines/networking/api-design.md
caching	Server sets correct Cache-Control — immutable for versioned assets, `private, max-age=N` for dynamic, `no-store` for sen	guidelines/networking/caching.md
content-security-policy	Server sets CSP header on all HTML responses; `default-src 'none'` baseline; nonce-based `script-src` with `strict-dynam	guidelines/security/content-security-policy.md
cors	Explicit static allowlist of origins, never reflect Origin, no wildcard with credentials, `Access-Control-Max-Age: 86400	guidelines/security/cors.md
error-responses	RFC 9457 Problem Details format with `Content-Type: application/problem+json`; machine-readable `type` URI, stable `titl	guidelines/networking/error-responses.md
offline-and-connectivity	Server supports ETag/version numbers for conflict detection (409 with both versions); delta sync via `last_synced_at`; o	guidelines/networking/offline-and-connectivity.md
pagination	Cursor pagination by default (`next_cursor`, `has_more`) for most APIs; offset (`offset`, `limit`, `total`) only when pa	guidelines/networking/pagination.md
python-dashboard-display-only	Dashboard service is a generic display layer — no git, file, or roadmap-structure knowledge; agents push data to it; it	guidelines/language/python/dashboard-service-is-display-only.md
python-database	SQLite with WAL mode (`PRAGMA journal_mode=WAL`), `sqlite3` standard library (no ORM), direct SQL queries	guidelines/language/python/database.md
python-deterministic-ids	IDs taken from YAML frontmatter UUID, never `uuid.uuid4()` or random generation; IDs must be reproducible across runs	guidelines/language/python/deterministic-ids.md
python-file-paths	`pathlib.Path` for all path operations, never `os.path` string concatenation; `Path.home()` for home-relative paths	guidelines/language/python/file-paths.md
python-no-external-deps	Core library (`roadmap_lib`) uses standard library only — no PyYAML, requests, or other third-party packages; keeps libr	guidelines/language/python/no-external-dependencies-in-core-librari.md
python-shell-scripts	`main()` functions delegate to named functions — no inline logic in main; composable and testable structure	guidelines/language/python/shell-scripts.md
python-type-hints	Type hints welcome but not required; Python 3.9 compatibility — use `from __future__ import annotations` or `typing` mod	guidelines/language/python/type-hints.md
python-use-roadmaplib	Use `roadmap_lib` functions for all roadmap operations (reading state, parsing frontmatter, finding steps); never reimpl	guidelines/language/python/use-roadmaplib.md
python-web-services	Flask for web services; REST API with SSE or polling for live updates; no other web frameworks	guidelines/language/python/web-services.md
python-yaml-frontmatter	Use `roadmap_lib`'s built-in frontmatter parser for `---` delimited frontmatter; no PyYAML dependency	guidelines/language/python/yaml-frontmatter.md
rate-limiting	Emit `Retry-After` header on 429 responses; expose `RateLimit-Remaining`/`RateLimit-Reset` headers proactively; apply pe	guidelines/networking/rate-limiting.md
real-time-communication	SSE endpoints for server-push (notifications, live feeds, progress); WebSocket only for bidirectional streaming; SSE use	guidelines/networking/real-time-communication.md
reliability-compliance	8 compliance checks — error-recovery (retry transient failures), graceful-degradation (handle unavailable dependencies),	compliance/reliability.md
retry-and-resilience	Idempotent endpoints (GET, PUT, DELETE) safe to retry; POST endpoints idempotency keys where needed; server-side circuit	guidelines/networking/retry-and-resilience.md
security-compliance	12 compliance checks — secure-authentication (OAuth/PKCE), server-side-authorization, secure-storage, input-sanitization	compliance/security.md
timeouts	All outbound HTTP calls have connection timeout (10s), read timeout (30s), total lifecycle timeout (60-120s); long-runni	guidelines/networking/timeouts.md

platform-web-frontend (27) platform

Team	Description	Cookbook Source
accessibility	WCAG 2.1 AA minimum; ARIA roles, states, properties (WAI-ARIA APG); keyboard navigation for all interactive elements; `a	guidelines/accessibility/accessibility.md
always-show-progress	Implement determinate progress bars (with percentage) and indeterminate spinners/skeletons/shimmer in the DOM; prevent U	guidelines/ui/always-show-progress.md
animation-motion	CSS transitions and JS animations use correct duration ranges per interaction type; `prefers-reduced-motion: reduce` med	guidelines/ui/animation-motion.md
api-design-client	Client calls match REST conventions — correct HTTP methods, no verb-in-URL, proper status code handling (201 for create,	guidelines/networking/api-design.md
caching	Immutable versioned assets use `Cache-Control: public, max-age=31536000, immutable`; sensitive data uses `no-store`; ETa	guidelines/networking/caching.md
color	CSS custom properties (not hard-coded hex), semantic color tokens per design system, WCAG AA contrast ratios, `prefers-c	guidelines/ui/color.md
content-security-policy	Implement `default-src 'none'` baseline, nonce-based script-src with strict-dynamic, no `unsafe-inline`/`unsafe-eval`, `	guidelines/security/content-security-policy.md
cors	Never reflect Origin header; static allowlist of permitted origins; no wildcard with credentials; `Access-Control-Max-Ag	guidelines/security/cors.md
data-display	Implement correct HTML patterns — `<ul>/<li>` for lists, `<table>` with sortable columns for tabular data, card grid for	guidelines/ui/data-display.md
error-responses-client	Parse RFC 9457 Problem Details (`application/problem+json`); display `detail` field to user; surface `errors[]` field fo	guidelines/networking/error-responses.md
feedback-patterns	Implement toast/snackbar (auto-dismiss 3-5s), inline alerts/banners, and modal dialogs; connect feedback weight to actio	guidelines/ui/feedback-patterns.md
form-design	Single-column layout, `<label>` top-aligned or floating, blur-event validation (not input-event), submit-event full vali	guidelines/ui/form-design.md
iconography	Use SVG icons with accessible names (`aria-label` or `<title>`), consistent size/weight classes, minimum 24x24px interac	guidelines/ui/iconography.md
layout	CSS Grid/Flexbox with responsive breakpoints via media queries (no hard-coded widths); single-column default expanding t	guidelines/ui/layout.md
offline-and-connectivity	Optimistic updates for most cases; outbox queue for mutations during offline; clear connectivity status indicator; no si	guidelines/networking/offline-and-connectivity.md
pagination-client	Client handles cursor-based pagination (`next_cursor`, `has_more`) and offset-based; infinite scroll or "Load more" for	guidelines/networking/pagination.md
platform-compliance	Web platform: WCAG 2.1 AA design language, native browser controls preferred, WCAG touch targets, dark mode and forced-c	compliance/platform-compliance.md
platform-design-languages	Web target follows WCAG 2.1 and browser/OS design conventions; use platform-appropriate system font stack; fill gaps wit	guidelines/ui/platform-design-languages.md
rate-limiting-client	Honor `Retry-After` header on 429; track `RateLimit-Remaining` and throttle proactively; queue/batch requests at allowed	guidelines/networking/rate-limiting.md
real-time-communication	Prefer SSE (`EventSource`) for server-push (notifications, live feeds, progress); WebSocket only for bidirectional strea	guidelines/networking/real-time-communication.md
retry-and-resilience-client	Exponential backoff with full jitter for transient failures (408, 429, 500, 502, 503, 504); max 3-5 retries for idempote	guidelines/networking/retry-and-resilience.md
spacing	CSS custom properties or design tokens for spacing on 4px scale (4/8/12/16/24/32/48/64); no arbitrary values in margin/p	guidelines/ui/spacing.md
state-design	Implement all four states in component templates — loading (skeleton/spinner), empty (illustration + message + CTA butto	guidelines/ui/state-design.md
timeouts-client	All fetch/XHR calls have connection timeout (10s), response timeout (30s), total lifecycle timeout (60-120s); no infinit	guidelines/networking/timeouts.md
touch-click-targets	Web minimum 24x24 CSS px (target 44x44), pad hit area beyond visual element via padding, ≥8px gap between adjacent targe	guidelines/ui/touch-click-targets.md
typography	System font stack, body 16px default, minimum 11-12px captions, line-height 1.4-1.5x, 2-3 weights per screen, paragraph	guidelines/ui/typography.md
visual-hierarchy	Single primary CTA per screen with `type="submit"` or strong visual weight; heading hierarchy via `<h1>`–`<h6>` and font	guidelines/ui/visual-hierarchy.md

platform-windows (18) platform

Team	Description	Cookbook Source
background-tasks	Use `BackgroundTask` with Windows App SDK for background execution; register triggers (time, network state change, push	guidelines/platform/background-tasks.md
csharp-naming	PascalCase for types, methods, properties, public fields, constants, namespaces; camelCase for parameters and local vari	guidelines/language/csharp/naming.md
deep-linking	Protocol activation via `<uap:Protocol>` declaration in `Package.appxmanifest`; handle activation through `AppInstance.G	guidelines/platform/deep-linking.md
dependency-injection	Constructor injection via `Microsoft.Extensions.DependencyInjection`; use interface types for dependencies (not concrete	guidelines/language/csharp/dependency-injection.md
design-time-data	Use `d:DataContext` and `d:DesignInstance` for XAML designer preview data; use XAML Hot Reload for live iteration during	guidelines/platform/windows/design-time-data.md
fluent-design	Use built-in WinUI 3 controls — they implement Fluent 2 natively; never custom-draw what a standard control can do; use	guidelines/platform/windows/fluent-design.md
handoff-and-continuity-windows	Windows does not have a native Handoff equivalent — use deep links as universal handoff payload; protocol activation URI	guidelines/platform/handoff-and-continuity.md
high-dpi-display-scaling	XAML layout uses effective pixels (epx) — scaling is automatic for XAML content; provide bitmap assets at multiple scale	guidelines/platform/windows/high-dpi-display-scaling.md
msix-packaging	Use single-project MSIX packaging model; declare capabilities minimally in `Package.appxmanifest`; sign packages with a	guidelines/platform/windows/msix-packaging.md
native-controls	Use platform built-in frameworks before custom implementations; WinUI 3 controls over custom-drawn equivalents; Windows	principles/native-controls.md
notifications-windows	Use `AppNotificationManager` + `AppNotificationBuilder` fluent API for local notifications; support text, images, button	guidelines/platform/notifications.md
nullable-reference-types	Enable `<Nullable>enable</Nullable>` in all projects; treat warnings as design signals — `string` means non-null, `strin	guidelines/language/csharp/nullable-reference-types.md
platform-compliance	7 compliance checks — platform-design-language (Fluent Design), native-controls-preference (WinUI 3 controls), platform-	compliance/platform-compliance.md
search-integration-windows	Use Windows Search indexer with `ISearchManager` and property handlers; register file type associations and protocol han	guidelines/platform/search-integration.md
share-and-inter-app-data-windows	Implement Share Contract (`DataTransferManager`) to send and receive content; register as share target in app manifest;	guidelines/platform/share-and-inter-app-data.md
shortcuts-and-automation-windows	Protocol activation for automation entry points; command-line activation via `AppInstance` APIs; WinUI 3 has limited scr	guidelines/platform/shortcuts-and-automation.md
theming	WinUI 3 tri-state theming — Light, Dark, High Contrast; set app-level theme via `Application.RequestedTheme`; always use	guidelines/platform/windows/theming.md
windows-architecture	MVVM with CommunityToolkit.Mvvm — source-generated `ObservableObject`, `RelayCommand`, and messaging; NavigationView + F	guidelines/platform/windows/architecture.md

project-management (6) pm

Team	Description	Cookbook Source
concerns	Risk identification, attention flagging, and monitoring of items needing review	.dev-team-project/concerns/
decisions	Decision recording with rationale, alternatives, and traceability	.dev-team-project/decisions/
dependencies	Internal and external dependency mapping, availability tracking, and risk assessment	.dev-team-project/dependencies/
issues	Problem identification, severity assessment, triage, and resolution tracking	.dev-team-project/issues/
schedule	Milestone definition, sequencing, target dates, dependency chains, and status tracking	.dev-team-project/schedule/
todos	Task breakdown, assignment, prioritization, and milestone linkage	.dev-team-project/todos/

reliability (3) domain

Team	Description	Cookbook Source
fail-fast	Invalid state detected and surfaced immediately at the point of origin; assertions and preconditions in debug builds; in	principles/fail-fast.md
idempotency	User actions and system operations safe to repeat without duplicate side effects; buttons debounced or disabled during a	principles/idempotency.md
reliability-compliance	8 compliance checks — error-recovery, graceful-degradation, fault-tolerance, state-recovery, idempotent-operations, time	compliance/reliability.md

security (15) domain

Team	Description	Cookbook Source
authentication	OAuth 2.0/OIDC with PKCE for public clients, system browser for native apps, no implicit flow, SSO and multi-client stra	guidelines/security/authentication.md
authorization	Deny by default, server-side enforcement only, least privilege scopes, RBAC, BOLA/IDOR prevention via resource ownership	guidelines/security/authorization.md
content-security-policy	default-src 'none' baseline, nonce-based script-src with strict-dynamic, never unsafe-inline or unsafe-eval, frame-ances	guidelines/security/content-security-policy.md
cors	Explicit origin allowlist (never reflect Origin), no wildcard with credentials, Access-Control-Max-Age, anchored regex f	guidelines/security/cors.md
dependency-security	Lockfiles committed, CI audit step (npm audit/pip-audit/Dependabot) failing on critical/high, pinned versions (no wildca	guidelines/security/dependency-security.md
input-validation	All validation duplicated server-side, allowlists over denylists, validate-sanitize-escape order, parameterized queries	guidelines/security/input-validation.md
privacy-and-data-compliance	7 compliance checks — data-minimization, consent-before-collection, secure-data-storage, no-pii-in-logs, data-retention-	compliance/privacy-and-data.md
privacy	Collect only what's needed, prefer on-device processing, opt-in consent for non-essential collection, app functional on	guidelines/security/privacy.md
secure-storage	Platform secure storage for all tokens/credentials/sensitive data — Keychain (Swift), EncryptedSharedPreferences (Kotlin	guidelines/security/secure-storage.md
security-compliance	7 compliance checks — secure-authentication, server-side-authorization, secure-storage, input-sanitization, secure-trans	compliance/security.md
security-headers-checklist	All 7 required headers on every web response — Strict-Transport-Security, Content-Security-Policy, X-Content-Type-Option	guidelines/security/security-headers-checklist.md
sensitive-data	Data minimization with explicit DTOs (not raw DB models), PII classification tiers, field-level encryption for SSN/payme	guidelines/security/sensitive-data.md
token-handling	Access token lifetime 5-15min, no PII in JWT claims, refresh token rotation, platform-appropriate secure storage	guidelines/security/token-handling.md
transport-security	TLS 1.2 minimum (prefer 1.3), disable TLS 1.0/1.1, HSTS with max-age=31536000 includeSubDomains preload, certificate pin	guidelines/security/transport-security.md
user-safety-compliance	6 compliance checks — content-moderation, age-appropriate-content, abuse-prevention, harmful-content-filtering, reportin	compliance/user-safety.md

software-architecture (8) domain

Team	Description	Cookbook Source
composition-over-inheritance	Default to composing behaviors from small, focused pieces; use inheritance only for genuine "is-a" relationships and eve	principles/composition-over-inheritance.md
concurrency-immutability	Default to immutable values; introduce mutability only where necessary; prefer value types over reference types; contain	guidelines/concurrency/immutability.md
concurrency	All lengthy work on background threads using platform async primitives (Swift Concurrency, Kotlin Coroutines, Promise/as	guidelines/concurrency/concurrency.md
dependency-injection	Components receive dependencies from outside, not constructed internally; pass services via constructor/initializer para	principles/dependency-injection.md
manage-complexity-through-boundaries	Define ports (interfaces) describing what the application needs; use adapters to translate between external technologies	principles/manage-complexity-through-boundaries.md
open-source-preference	When no native solution exists, research battle-tested open-source libraries and present options before building custom;	principles/open-source-preference.md
optimize-for-change	Every architectural decision evaluated by whether it makes future change easier or harder; all other principles (composi	principles/meta-principle-optimize-for-change.md
separation-of-concerns	Each module has one reason to change; if describing what a module does requires "and," consider splitting; applies at ev	principles/separation-of-concerns.md

testing-qa (12) domain

Team	Description	Cookbook Source
flaky-test-prevention	No shared mutable state between tests, no execution-order dependencies, no real network calls in unit tests, no sleep()	guidelines/testing/flaky-test-prevention.md
mutation-testing	Run mutation testing before claiming tests are complete; platform tools: mutmut (Python), Stryker (TypeScript/JS/.NET),	guidelines/testing/mutation-testing.md
post-generation-verification	Every generated artifact must pass 6 steps — build (all platforms), test (full suite), lint (platform linter), log verif	guidelines/testing/post-generation-verification.md
properties-of-good-tests	Tests should be isolated, composable, deterministic, fast, writable, readable, behavioral (test what not how), structure	guidelines/testing/properties-of-good-tests.md
property-based-testing	Use for parsers, serializers, data transformers, encoders/decoders, validators — anything where "for all valid inputs X,	guidelines/testing/property-based-testing.md
security-testing	Run SAST (Semgrep all languages, Bandit for Python, CodeQL for deep analysis), dependency scanning (pip-audit, npm audit	guidelines/testing/security-testing.md
test-data	Construct test data per test; avoid large shared fixture files; use builder pattern or factory functions for complex obj	guidelines/testing/test-data.md
test-doubles	Use Martin Fowler's taxonomy (Dummy/Stub/Spy/Mock/Fake); prefer fakes over mocks — fakes exercise real behavior; never m	guidelines/testing/test-doubles.md
test-pyramid	80% unit / 15% integration / 5% E2E; unit tests are fast and isolated; integration tests use real databases/filesystems/	guidelines/testing/test-pyramid.md
testing	Every change needs tests, every bug fix needs a regression test; prioritize unit tests over integration; test state tran	guidelines/testing/testing.md
the-testing-workflow	Complete closed-loop workflow — write implementation, write unit tests (with property-based for data transforms), run te	guidelines/testing/the-testing-workflow.md
unit-test-patterns	AAA structure (Arrange/Act/Assert), one assertion concept per test, no logic in tests (no if/for/try-catch), test the pu	guidelines/testing/unit-test-patterns.md

ui-ux-design (17) domain

Team	Description	Cookbook Source
always-show-progress	Determinate progress (bar with percentage) when total work is known; indeterminate (spinner, skeleton, shimmer) when not	guidelines/ui/always-show-progress.md
animation-motion	Purposeful motion only — guide attention, show spatial relationships, provide feedback; duration defaults by interaction	guidelines/ui/animation-motion.md
color	Semantic color tokens (not hard-coded hex), limited palette (1 primary + neutrals + semantic), color never the sole stat	guidelines/ui/color.md
data-display	Right pattern for content type — list for sequential/scannable, table for comparable multi-attribute, cards for heteroge	guidelines/ui/data-display.md
feedback-patterns	Feedback weight matches action weight — inline for fields, toast for non-critical confirmations (3-5s auto-dismiss), ban	guidelines/ui/feedback-patterns.md
form-design	Single-column layout, top-aligned/floating labels, validate on blur (not keystroke), full-form validation on submit, inl	guidelines/ui/form-design.md
iconography	Platform-native icon set first (SF Symbols, Material Symbols, Segoe Fluent Icons), all action icons have text label or a	guidelines/ui/iconography.md
layout	Single-column by default, content-first decisions, consistent alignment, responsive breakpoints via platform adaptive sy	guidelines/ui/layout.md
least-astonishment	UI behavior matches user expectations — names deliver the behavior they imply, side effects are obvious, no surprising o	principles/principle-of-least-astonishment.md
platform-compliance	Platform design language followed (HIG/Material/Fluent), native controls preferred, platform touch targets met, platform	compliance/platform-compliance.md
platform-design-languages	Defer to platform HIG (Apple HIG, Material 3, Fluent 2, WCAG 2.1) before applying defaults; use platform-prescribed valu	guidelines/ui/platform-design-languages.md
previews	All UI components include preview declarations covering all significant states (default, loading, error, empty, populate	guidelines/ui/previews.md
spacing	4px base unit (8px primary grid), all spacing on scale 4/8/12/16/24/32/48/64, no arbitrary values (5px, 13px, 37px)	guidelines/ui/spacing.md
state-design	All four states explicit — loading (skeleton for content-heavy, spinner for actions), empty (icon + message + CTA), erro	guidelines/ui/state-design.md
touch-click-targets	Platform minimums — iOS 44x44pt, Android 48x48dp, Windows 32x32epx (40 recommended), Web 24x24px (44 recommended); visua	guidelines/ui/touch-click-targets.md
typography	Platform system font (SF Pro, Roboto, Segoe UI Variable, system-ui), body 14-17pt (16px default), minimum 11-12pt for ca	guidelines/ui/typography.md
visual-hierarchy	One primary action/focal point per screen, size and weight (not just color) for heading levels, proximity for grouping,	guidelines/ui/visual-hierarchy.md

File Format spec

Each file lives at specialty-teams/<category>/<name>.md with YAML frontmatter and two sections:

--- name: authentication description: OAuth 2.0/OIDC with PKCE, SSO, multi-client strategies artifact: guidelines/security/authentication.md version: 1.0.0 --- ## Worker Focus OAuth 2.0/OIDC with PKCE for public clients, system browser for native apps, no implicit flow, SSO strategies ## Verify No implicit flow; PKCE code_challenge present; system browser on native; no client_secret in public clients

artifact — the cookbook guideline, principle, or compliance check this team analyzes. Worker Focus — what matters (mode-independent). Verify — concrete acceptance criteria for the verifier.

How Specialists Reference Teams manifest

Each specialist has a ## Manifest section listing its teams by file path:

## Manifest - specialty-teams/security/authentication.md - specialty-teams/security/authorization.md - specialty-teams/security/token-handling.md - specialty-teams/security/transport-security.md ...

The script run-specialty-teams.sh reads the manifest and outputs JSON for each team (name, artifact, worker_focus, verify). Workers and verifiers consume this JSON — they never read the specialty-team files directly.

05bConsulting-Teams

Cross-cutting verification gates. Some specialists have consulting-teams that review every specialty-team's output for interdependent concerns that no single team owns.

When Consulting-Teams Are Used verification

Most specialists do not need consulting-teams. They are designed for specialists whose domains have deeply interdependent concerns — where the output of one specialty-team can contradict or invalidate another's findings.

Example: The database specialist has consulting-teams because schema design, query optimization, migration strategy, and indexing are tightly coupled. A schema change that satisfies normalization principles might break the performance team's indexing recommendations. A consulting-team catches these conflicts.

Two verdicts: VERIFIED means the cross-cutting concern applies and the specialty-team's findings hold up under scrutiny. NOT-APPLICABLE means the concern does not apply to this particular team's scope — this is a valid outcome, not a failure.

Verifier independence: Just like specialty-teams, consulting workers and verifiers never see each other's instructions. The verifier checks the worker's assessment independently.

06Agents

20 agent definitions in agents/. Each is a markdown file with instructions for a specific role.

All Agents (20) agents

Agent	Purpose
specialty-team-worker	Reads one cookbook guideline or principle, produces structured findings
specialty-team-verifier	Checks worker output for completeness, returns PASS/FAIL
consulting-team-worker	Reviews specialty-team output through a cross-cutting lens, produces VERIFIED or NOT-APPLICABLE
consulting-team-verifier	Checks consulting worker assessment for completeness, returns PASS/FAIL
transcript-analyzer	Analyzes interview transcripts for coverage and gaps
specialist-analyst	Analyzes user answers from a specialist perspective
code-generator	Generates source code from cookbook recipes
recipe-writer	Creates cookbook recipes from analyzed code
recipe-reviewer	Reviews recipes against cookbook standards
project-scaffolder	Creates project directory structure
project-assembler	Assembles cookbook project from components
scope-matcher	Matches code components to cookbook scopes
codebase-scanner	Scans and analyzes existing codebases
build-runner	Runs builds and reports results
smoke-tester	Runs smoke tests on generated code
code-comparator	Compares two code projects for differences
artifact-reviewer	Reviews files against cookbook standards
specialist-aligner	Checks specialist-cookbook alignment
specialist-code-pass	Sequential specialist augmentation of code (v1, marked for absorption)
specialist-interviewer	Specialist-perspective interview questions (v1, marked for absorption)

07Arbitrator

Abstracted communication conduit between all participants. The arbitrator handles ALL data exchange — participants never know how storage works.

API Overview communication

Single entry point: scripts/arbitrator.sh <resource> <action> [--flags]

Backend-swappable via ARBITRATOR_BACKEND env var (default: markdown). All commands output JSON to stdout, errors to stderr, exit 0/1. IDs are opaque strings.

Resource	Actions	Purpose
session	create, get, list, add-path	Workflow run lifecycle
state	append, current, list	Append-only state transitions
message	send, list, get	Team-lead ↔ user interaction
gate-option	add	Choices for gate messages
result	create, get, list	Specialist output bundles
finding	create, list, get, link-artifact	Individual issues within results
interpretation	create, list	Persona translations of findings
artifact	create, list, link-state	Cookbook artifacts referenced
reference	create, list	Cookbook sources consulted
retry	create, list	Retry reasons
report	overview, specialist, finding, trace	Progressive disclosure queries

Markdown Backend storage

Stores JSON files in ~/.agentic-cookbook/dev-team/sessions/<session-id>/

<session-id>/ session.json paths.jsonl state/          # append-only transitions messages/       # chronological gate-options/   # per-message choices results/ <specialist>/ result.json findings/ interpretations/ references/ artifacts/ retries/

72 contract tests validate the API regardless of backend.

08Project Storage

Abstract CRUD API for dev-team-project data. A dev-team-project tracks project management concerns — schedules, tasks, issues — not code specifications.

API Overview storage

Single entry point: scripts/project-storage.sh <resource> <action> [--flags]

Backend-swappable via PROJECT_STORAGE_BACKEND env var (default: markdown). Full CRUD: create, get, list (with filters), update, delete.

Resource	Actions	Purpose
project	init, status, link-cookbook, unlink-cookbook	Project lifecycle
milestone	create, get, list, update, delete	Schedule targets
todo	create, get, list, update, delete	Tasks with assignment and priority
issue	create, get, list, update, delete	Problems, blockers, risks
concern	create, get, list, update, delete	Items needing attention
dependency	create, get, list, update, delete	Internal and external dependencies
decision	create, get, list, update, delete	Choices with rationale

Markdown Backend storage

Items stored as markdown files with YAML frontmatter in .dev-team-project/

.dev-team-project/ manifest.json schedule/       # milestone-NNNN-<slug>.md todos/          # todo-NNNN-<slug>.md issues/         # issue-NNNN-<slug>.md concerns/       # concern-NNNN-<slug>.md dependencies/   # dependency-NNNN-<slug>.md decisions/      # decision-NNNN-<slug>.md

64 contract tests validate the API regardless of backend.

09Observers

System-level observation of subagent activity via Claude Code hooks. Zero changes to agents or orchestration — observers capture process narrative deterministically.

Architecture system

The observer system uses a SubagentStop hook configured in .claude/settings.json. When any subagent completes, dispatch.py reads the agent transcript JSONL, extracts a normalized event (tools used, duration, status, summary), and dispatches to all auto-discovered observer modules in scripts/observers/.

Zero agent changes — observers are invisible to participants. The pipeline doesn't know it's being observed.

Deterministic — no LLM involved. Pure data extraction from transcript JSONL.

Extensible — drop a .py file with def observe(event: dict) into scripts/observers/. Auto-discovered at dispatch time.

Built-in Observers (2) observers

Observer	Output	Purpose
stenographer	session.log (JSONL)	Structured session log — timestamp, agent type, description, status, duration, tools used, call count, summary
oslog	system log	Real-time one-liners via POSIX `logger` CLI — visible in Console.app or `log stream`

Normalized Event schema

Every observer receives the same event dict:

{ "timestamp": "2026-04-06T...", "session_id": "abc123", "agent_id": "a1b2c3d4", "agent_type": "general-purpose", "agent_description": "Create schema files", "status": "completed", "duration_ms": 45200, "tools_used": ["Read", "Write", "Glob"], "tool_call_count": 12, "summary": "Created 9 specialty team files..." }

10Data Flow

Two abstraction layers handle all data exchange. Neither reveals its storage implementation to callers.

Communication (Arbitrator) user ↔ team-lead (messages, gates, verdicts, notifications)team-lead ↔ specialist (assignments, results, state transitions)specialist ↔ specialty-team (findings, verifications, retries)Project Management (Project-Storage-Provider)project-manager ↔ project-storage-provider ↔ .dev-team-project/

Design Principles architecture

Arbitrator is communication only. It carries messages between participants. Domain-specific data goes through its own specialist and storage provider.

Backends are swappable. Both the arbitrator and project-storage-provider use a dispatcher + backend pattern. The markdown backend is first; database backend comes later.

Reports are queries, not stored types. Progressive disclosure: overview → specialist → finding detail → process trace. Designed for LLM consumption.

Shell scripts for deterministic work. Orchestration, file management, and data operations are shell scripts. LLM agents handle judgment tasks only.

11Configuration

Minimal config. Created on first run of /dev-team interview.

~/.agentic-cookbook/dev-team/config.json { "workspace_repo": "<path to workspace repo>", "cookbook_repo": "<path to agentic-cookbook>", "user_name": "<user name>", "authorized_repos": [] }

12File Map

Repository structure at a glance.

.claude-plugin/              Plugin manifest agents/                      20 agent definitions specialists/                 20 specialists (13 domain + 6 platform + 1 PM) specialty-teams/             231 specialty-team files in 20 categories consulting-teams/            Consulting-team files (cross-cutting verification) skills/ dev-team/ SKILL.md                 Router (v0.6.0) workflows/               One workflow file per subcommand scripts/ arbitrator.sh              Communication conduit dispatcher arbitrator/markdown/       12 resource scripts project-storage.sh         Project management storage dispatcher project-storage/markdown/  8 scripts db/                        Database shell script API run-specialty-teams.sh     Parses specialist manifests to JSON observers/ dispatch.py              Hook entry point (SubagentStop) _lib.py                  Shared utilities stenographer.py          Session log observer (JSONL) oslog.py                 System log observer (logger CLI) services/ dashboard/                 Live workflow dashboard (Flask, port 9876) docs/ architecture.md            Single source of truth specialist-spec.md         Formal specialist file specification specialist-guide.md        How specialists and specialty-teams work

13Tests

Backend-agnostic contract tests validate APIs regardless of storage implementation.

Suite	Tests	Coverage
tests/arbitrator/	72	All 11 arbitrator resources: session lifecycle, state transitions, messages, gates, results, findings, interpretations, artifacts, references, retries, reports, consulting reviews, error handling
tests/project-storage/	64	All 7 project-storage resources: project lifecycle, milestones, todos, issues, concerns, dependencies, decisions, CRUD, filtering, error handling
tests/specialty-teams/	2330+	File structure, frontmatter, content, script output, manifest integrity across 231 specialty-team files

# Run arbitrator contract tests bash tests/arbitrator/run-contract-tests.sh # Run project-storage contract tests bash tests/project-storage/run-contract-tests.sh