Skip to content

010-expert-context-workflow.md

Latest commit

 

History

History
165 lines (116 loc) · 8.03 KB

010-expert-context-workflow.md

File metadata and controls

165 lines (116 loc) · 8.03 KB
Raw

ADR-010: Expert-Context Workflow — One Universal Workflow

  • Status: Accepted
  • Date: 2026-03-15
  • Decision makers: Sebastien (plugin author)
  • Supersedes: ADR-008 (Archetype Architecture)
  • Depends on: ADR-007 (becoming mechanism), ADR-004 (orchestration pattern), ADR-009 (namespace compliance)

Context

ADR-008 Got the Problem Right but the Solution Wrong

ADR-008 correctly identified the problem: ACD's session commands assume software deliverables. The plugin needs to serve non-software work (marketing, strategy, content, architecture, discovery) with the same discipline.

ADR-008's solution — archetype-prefixed commands (dev-*, craft-*) — was wrong for two reasons:

  1. "Craft" is not the opposite of "dev." A developer crafts code. Every expert crafts work in their domain. The word describes quality, not type.
  2. Prefixes multiply commands. Two archetypes = 18 commands. Three = 27. This contradicts the "one intelligent assistant" vision.

The MinimumCD Spec Describes One Universal Workflow

Re-reading the ACD specification, the six first-class artifacts use universal language:

  • User-Facing Behavior: "Observable outcomes, often as BDD scenarios" — not always
  • Acceptance Criteria: "Test cases and evaluation designs" — broader than tests
  • The four-step cycle: "human drafts, agent critiques, human decides, agent refines" — domain-agnostic
  • Session unit: "One scenario. One session. One commit." — one unit of work, not necessarily BDD

The workflow order is universal:

  1. /acd:specify — capture intent with hypothesis, generate artifacts
  2. /acd:validate-spec — check consistency across artifacts
  3. /acd:start-session — load one unit of work
  4. (work happens)
  5. /acd:review — quality gate before committing
  6. /acd:end-session — validate, summarize, commit
  7. /acd:finalize — archive, check hypothesis

What changes per domain is artifact format and quality gate, not the workflow.

The Six Artifacts Generalize

Artifact Software Marketing Architecture
Intent "We believe [code change] will [outcome]" "We believe [positioning] will [outcome]" "We believe [structure] will [outcome]"
Behavior BDD scenario (Gherkin) Audience response criteria Quality attribute scenario
Constraints Musts / Must Nots / Preferences Brand guidelines, tone, audience System boundaries, budgets
Acceptance Tests pass Review rubric pass Constraint compliance
System constraints Performance, security Legal, brand, compliance Organizational standards
Implementation Code Document / copy / visual Decision record / diagram

The Intent Determines the Expert Context

The expert context doesn't need configuration flags or menus. It emerges from the intent:

  • "Add rate limiting to /api/search" → software engineering
  • "Write a positioning brief for the agency" → marketing
  • "Create a landing page for the new service" → software + marketing + design

The expert-summoning skill already maps domains to the right expertise. The commands just need to let the intent drive which skills load.

Token-Efficient Context Architecture

The concern about mixing domains (loading marketing context during a CSS fix) is solved by Claude Code's existing loading hierarchy:

  1. Plugin skills — descriptions always loaded (one line each, cheap). Full content loads only when relevant to the session.
  2. Project CLAUDE.md — lean root (~50 lines: goal, expert contexts). Always loaded.
  3. Subdirectory CLAUDE.md — domain-specific decisions. Loaded only when working in that directory.

See docs/c4-context-architecture.md for the full diagram.

This means a software session doesn't pay for marketing decisions, and a marketing session doesn't pay for TypeScript conventions — even within the same project.

Decision

One set of unprefixed commands

Revert the dev-* prefix. The plugin has ONE workflow:

commands/
├── specify.md              → /acd:specify
├── validate-spec.md        → /acd:validate-spec
├── start-session.md        → /acd:start-session
├── review.md               → /acd:review
├── end-session.md          → /acd:end-session
├── fix.md                  → /acd:fix
├── finalize.md             → /acd:finalize
├── maintenance.md          → /acd:maintenance
├── security-audit.md       → /acd:security-audit
├── init-project.md         → /acd:init-project
├── evaluate.md             → /acd:evaluate
├── learn.md                → /acd:learn
└── become.md               → /acd:become

Expert context flows from intent

No --context flags. No project-level configuration menus. The workflow:

  1. User writes intent in /acd:specify — includes hypothesis
  2. The intent's domain signals which skills are relevant
  3. Claude loads the relevant skills (descriptions are always available; full content loads on demand)
  4. Review agents check from the relevant expert perspectives
  5. If the intent spans multiple domains (landing page = engineering + marketing + design), multiple skills load

For a pure software project, this is identical to the current experience. The expert context machinery is invisible — skills load because they're relevant, not because someone configured a context.

Domain adaptation lives in skills, not commands

Each practice/technology skill can include a session profile section defining:

  • Artifact formats — what "behavior" and "acceptance criteria" look like in this domain
  • Review criteria — what review agents check
  • Quality gate — what must pass before committing
  • Session unit — what constitutes one deliverable unit

Adding a new domain = adding a skill (via /acd:learn). No command changes ever needed.

Project organization for multi-domain work

For projects spanning multiple domains (e.g., a website needing both engineering and marketing):

project/
├── CLAUDE.md                    ← lean: goal + available expert contexts
├── src/
│   └── .claude/CLAUDE.md        ← engineering-specific: stack, conventions
├── docs/marketing/
│   └── .claude/CLAUDE.md        ← marketing-specific: positioning, audience
└── docs/content/
    └── .claude/CLAUDE.md        ← content-specific: editorial, pillars

Claude Code auto-discovers subdirectory CLAUDE.md files when working in those directories. The root stays lean. Each domain's decisions load only when you're working there.

Consequences

Positive

  • 13 commands, not 18+. No growth with new domains.
  • True "one intelligent assistant." Same commands, any domain.
  • Becoming mechanism integration. /acd:learn creates a skill → workflow extends to that domain automatically.
  • Aligns with MinimumCD spec. One universal workflow, domain-adapted.
  • Token efficient. Skills load on demand. Subdirectory CLAUDE.md files scope project decisions.

Negative

What Happens to ADR-008

Superseded. Its problem analysis was correct. Its solution (archetype prefixes) was premature specialization replaced by intent-driven expert context.

What Happens to ADR-009

Remains valid. The name: field removal and filename-derived names are correct regardless of what the filenames are.

Validation Criteria

  1. /acd:start-session works for software — identical to current behavior
  2. /acd:start-session works for non-software — loads appropriate skills and review criteria
  3. /acd:specify generates domain-appropriate artifacts based on the intent's domain
  4. /acd:review dispatches domain-appropriate review based on the session's expert context
  5. A project with multiple expert contexts can switch between them across sessions
  6. Adding a new expert context requires only a new skill — no command changes
  7. A software-only project experiences zero additional friction from the expert context system