feat(aep): add /aep-model object-first design stage (OOUX/ORCA)#13
Merged
Conversation
Capture the verb-first (USM) vs noun-first (OOUX/OOUI) analysis and the feasibility verdict for auto-generating UI structure across AEP design stages. ORCA's four rounds map onto inputs AEP already produces, so an automated Object Map can bridge the story map → UI gap that calibration (style + human choice only) currently leaves open. Sourced live this session (defuddle/WebFetch on ooux.com + the Medium intro) on top of the prior adversarially-verified Task-vs-Object note. AEP integration (/aep-model skill, design/object-map.yaml) is analysis only in §7 and deferred to a follow-up. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Keep codex's §7 (v2 split-context artifacts, ux-flow accuracy fix, draft→review→approved gate) and the docs README Research category. Only revert the quote paraphrasing: §2/§3/§4 carry the exact ooux.com quotes again (verified verbatim against this session's defuddle/WebFetch), and the method line records reproducibility (mgrep --web quota exhausted). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bridge the verb-first story map to the UI with a noun-first Object Map so build agents stop inventing one-step-one-screen task-wizard UIs. Realizes §7 of docs/research/ooux-object-modeling.md. New: - skills/product-context/model/ — /aep-model: ORCA draft → human review gate → approved Object Map (between /aep-map and /aep-dispatch) - _shared/templates/object-model-schema.yaml (product/object-model.yaml, cross-capability ontology) + object-map-schema.yaml (product/maps/<cap>/object-map.yaml, capability ORCA/IA projection) - model/references/orca-process.md — ORCA derivation + object-first/ task-oriented decision framework Wiring (additive, gated like calibration): - schema: stories[].object_model_refs, object-model quality dimension, thin calibration.history reference (artifacts stay under product/) - envision: declare object-model gate for UI-facing products - map: auto-draft Object Maps after decomposition; Next Step → /aep-model - dispatch: inject minimal Object Map slice; refuse UI story w/o approved map - launch: Guardrail 4 aborts UI story w/o approved Object Map - build: UI implementation obeys the injected Object Map slice - validate: Mode A Object Map completeness checks - docs: glossary terms, orientation skill table, README Object-first is the default; task-oriented flows are an opt-in escape hatch recorded with a reason. Structural only — visual/voice/journey stay in /aep-calibrate. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Three independent gen/eval agents (generator dry-run, evaluator vs repo, protocol checker) converged on a real producer↔consumer gap plus doc drift. BLOCKING: - story→capability was unresolvable (no field; launch grepped a literal <capability> placeholder). Add stories[].capability + modules[].kind; resolve via story.capability with a coverage-scan fallback; rewrite the dispatch slice + launch Guardrail 4 to scan product/maps/*/object-map.yaml by covered story id. Define the v1/single-journey default capability (project slug). - pin the canonical screen-id grammar (<object-id>:<view>) so the dispatch slice is parseable; define object_model_refs fragment grammar. IMPORTANT: - draft ownership: /aep-map drafts, /aep-model refines in place (not regenerate); generated_by reflects author. - stale lifecycle: /aep-map flips an approved map to `stale` on re-decompose; dispatch/launch/validate treat stale like draft (abort → /aep-model). - doc drift: reconcile skill count (19) across orientation + README; add /aep-model to dispatch/validate "Where this fits" + README All Skills. - derivation rubrics (confidence, CTA priority, attribute tiers), frame.yaml/ v1 fallback, calibrated_from_layer anchor, primary_objects precision, map.yaml filename. build-skills in sync; schema YAML parses. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bump marketplace.json 2.0.1 → 2.1.0 (minor: additive new skill + capability) and register the new product-context/model skill in the plugin manifest (was missing — it would not have installed). Add the matching CHANGELOG entry. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Place the noun-first Object Map step in the detailed Product Context plugin flow (between the topology merge and /aep-dispatch, alongside /aep-calibrate), and add a caption to the conceptual Mental Model diagram noting the specialized control-plane steps it omits (/aep-model, /aep-calibrate, /aep-validate, /aep-watch). Trim the now-redundant prose note. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
AEP's design spine is verb-first (Jeff Patton USM):
/aep-envision→ activity backbone,/aep-map→ layered story graph. That plans what the user does but never what the UI looks like structurally —/aep-calibrateonly locks style (visual-design) and human choice. With no noun-first object model bridging the story map to the UI, build agents invent screen structure per story, which drifts into the disjointed task-wizard UIs that OOUX/OOUI criticize.This PR adds an automated OOUX/ORCA object-modeling stage between
/aep-mapand/aep-dispatch. It derives a noun-first Object Map (objects → relationships → CTAs → attributes → screens) from artifacts AEP already produces, takes a short human approval, then governs object structure so the structural UI plan is done before build — leaving only taste (look/voice/journey) to calibration.Realizes §7 of the research note included in this PR.
Contents
Research (3 commits) —
docs/research/ooux-object-modeling.md: verb-first vs noun-first analysis, full ORCA process (cited from ooux.com + Medium, cross-checked), the feasibility verdict, and the §7 AEP-integration design.Implementation (1 commit)
skills/product-context/model/—/aep-model: ORCA draft → human review gate → approved Object Map. Authoredreferences/orca-process.md._shared/templates/object-model-schema.yaml(cross-capability ontology,product/object-model.yaml) +object-map-schema.yaml(capability projection,product/maps/<cap>/object-map.yaml).stories[].object_model_refs+object-modeldimension in the schema; envision declares the gate for UI-facing products; map auto-drafts after decomposition; dispatch injects the minimal slice and refuses UI stories without an approved map; launch Guardrail 4 aborts likewise; build obeys the injected slice; validate Mode A adds Object Map completeness checks.Design choices
task_orientedescape hatch recorded with a reason (onboarding/checkout/wizard) — per the decision framework in the research note §6./aep-calibrate.product/;product-context.yamlkeeps only thin references (per code-review feedback on the research note)./aep-mapSystem Map gate); the stage drafts, the human approves.Verification
bash scripts/build-skills.sh --check— generated resources in sync_shared/modelschema YAML parses (python3 -c "import yaml")product-context.yamlships in this repo, so end-to-end/aep-modeldry-run must be exercised in a downstream project.🤖 Generated with Claude Code