Skip to content

feat(aep): add /aep-model object-first design stage (OOUX/ORCA) #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
memorysaver merged 9 commits into from
Jun 16, 2026
Merged

feat(aep): add /aep-model object-first design stage (OOUX/ORCA) #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
1f39aaa
docs(research): add OOUX/OOUI object-modeling × AEP study
memorysaver Jun 16, 2026
7e1358a
docs(research): refine OOUX object-modeling review
memorysaver Jun 16, 2026
4ce3685
docs(research): restore verbatim primary quotes + tool provenance
memorysaver Jun 16, 2026
0f3961b
feat(aep): add /aep-model object-first design stage (OOUX/ORCA)
memorysaver Jun 16, 2026
bed3e1e
fix(aep): address gen/eval findings on object-modeling stage
memorysaver Jun 16, 2026
8b5fc6f
chore: release v2.1.0 — /aep-model object-first design stage
memorysaver Jun 16, 2026
c6363f4
docs(changelog): fix wrapped-bullet wording in v2.1.0 entry
memorysaver Jun 16, 2026
39fa591
docs(readme): add /aep-model to the Product Context flow diagram
memorysaver Jun 16, 2026
c0c62d6
docs: replace workflow ascii art with diagrams
memorysaver Jun 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .claude-plugin/marketplace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,19 @@
"email": "mho@looplia.run"
},
"metadata": {
"version": "2.0.1",
"version": "2.1.0",
"description": "Skills for product planning, project scaffolding, and agentic development workflows."
},
"plugins": [
{
"name": "product-context",
"description": "Product-level planning and iteration: envision, map, dispatch, validate, calibrate, reflect, watch.",
"description": "Product-level planning and iteration: envision, map, model, dispatch, validate, calibrate, reflect, watch.",
"source": "./",
"strict": false,
"skills": [
"./skills/product-context/envision",
"./skills/product-context/map",
"./skills/product-context/model",
"./skills/product-context/dispatch",
"./skills/product-context/validate",
"./skills/product-context/calibrate",
Expand Down
53 changes: 53 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,59 @@ bug fixes → **patch**; removing or breaking a skill contract → **major**.

_Nothing yet._

## [2.1.0] - 2026-06-16

Add an **object-first design stage** — `/aep-model` — that turns the verb-first
story map into a noun-first **Object Map** (OOUX/ORCA) before UI is built, so build
agents stop inventing one-step-one-screen task-wizard UIs. The structural UI plan
(objects, attributes, relationships, CTAs, screens) is auto-drafted from artifacts
AEP already produces, human-approved at a short gate, then governs build — leaving
only taste (look/voice/journey) to `/aep-calibrate`. Background and the verb-first
vs noun-first analysis: [`docs/research/ooux-object-modeling.md`](docs/research/ooux-object-modeling.md).

### Added

- **`/aep-model` skill** (`product-context`): runs ORCA (Objects → Relationships →
Calls-to-action → Attributes → screens) to draft an Object Map, takes a short
human review gate (object boundaries, primary anchor, task-flow exceptions), and
writes the approved noun-first blueprint. Sits between `/aep-map` and
`/aep-dispatch` for UI-facing products. Registered in
[`marketplace.json`](.claude-plugin/marketplace.json) `product-context` plugin.
- **Object Map artifacts + schemas**: `product/object-model.yaml` (cross-capability
object ontology) and `product/maps/<capability>/object-map.yaml` (capability-scoped
ORCA/IA projection), via `_shared/templates/object-model-schema.yaml` and
`object-map-schema.yaml`. Object-first is the default; task-oriented flows are an
opt-in escape hatch recorded with a reason.
- **ORCA reference** (`product-context/model/references/orca-process.md`):
round-by-round derivation from AEP inputs + the object-first/task-oriented decision
framework and the completeness checks.
- **Glossary terms**: Object Model, Object Map, ORCA, Call-to-Action (CTA), Nested
Object Matrix, Object-First vs Task-Oriented.
- **Research note** `docs/research/ooux-object-modeling.md` and a `Research` category
in [`docs/README.md`](docs/README.md).

### Changed

- **Schema** (`product-context-schema.yaml`): adds `stories[].object_model_refs`,
`stories[].capability`, `architecture.modules[].kind`, and the `object-model`
quality dimension. Object-map approvals are tracked as thin `calibration.history`
references — the artifact bodies stay under `product/`, not inlined into
`product-context.yaml`.
- **`/aep-envision`**: declares the `object-model` structural gate by default for
UI-facing products.
- **`/aep-map`**: auto-drafts Object Maps after decomposition; sets `module.kind` +
`story.capability`; flips an approved map to `stale` on re-decompose; routes Next
Step to `/aep-model`.
- **`/aep-dispatch`**: injects the minimal Object Map slice into a story's context
package and refuses UI-facing stories without an approved (non-stale) map.
- **`/aep-launch`**: aborts a UI-facing story when no approved Object Map covers it.
- **`/aep-build`**: UI implementation obeys the injected Object Map slice (object structure and CTA grammar; taste still from calibration).
- **`/aep-validate`**: Mode A gains Object Map completeness checks (coverage, object
homes, anchors, task-flow justification, ref resolution).

All additions are backward-compatible — the object-model path only engages for
UI-facing products that opt in.

## [2.0.1] - 2026-06-16

Operationalize the **dogfood → reflect classifier → story** link so the G6
Expand Down
102 changes: 14 additions & 88 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,12 +238,12 @@ npx skills experimental_install

The `skills` CLI selects by skill name (there's no "group" flag). The groups map to these `--skill` names:

| Group | `--skill` names |
| ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Workflow** (agentic-development-workflow) | `aep-design`, `aep-launch`, `aep-build`, `aep-wrap`, `aep-git-ref` |
| **Product** (product-context) | `aep-envision`, `aep-map`, `aep-dispatch`, `aep-validate`, `aep-calibrate`, `aep-reflect` |
| **Setup** (project-setup) | `aep-onboard`, `aep-scaffold`, `aep-testing-guide` |
| **Patterns** (patterns) | `aep-gen-eval`, `aep-executor`, `aep-autopilot`, `aep-workflow-feedback` |
| Group | `--skill` names |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Workflow** (agentic-development-workflow) | `aep-design`, `aep-launch`, `aep-build`, `aep-wrap`, `aep-git-ref` |
| **Product** (product-context) | `aep-envision`, `aep-map`, `aep-model`, `aep-dispatch`, `aep-validate`, `aep-calibrate`, `aep-reflect` |
| **Setup** (project-setup) | `aep-onboard`, `aep-scaffold`, `aep-testing-guide` |
| **Patterns** (patterns) | `aep-gen-eval`, `aep-executor`, `aep-autopilot`, `aep-workflow-feedback` |

### Maintainer (legacy) workflow

Expand Down Expand Up @@ -282,57 +282,9 @@ bun run skills:check # verify the copies are in sync (also runs in CI + pre-c

The workflow separates **thinking** from **doing**:

```
┌─────────────────────────────────────────────────────────────────┐
│ │
│ CONTROL PLANE (human decides what to build) │
│ │
│ You + AI collaborate on high-leverage decisions: │
│ goals, decomposition, architecture, priorities, feedback │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ /aep-envision │───►│ /aep-map │───►│ /aep-reflect │──┐ │
│ │ │ │ │ │ │ │ │
│ │ what to │ │ how to │ │ what we │ │ │
│ │ build │ │ break it │ │ learned │ │ │
│ │ │ │ down │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ │ │
│ ▲ │ │ │ │
│ └────────────────┼──────────────┘ │ │
│ │ feedback loop │ │
│ ▼ │ │
│ ┌────────────┐ │ │
│ │ /aep-dispatch │ picks stories │ │
│ │ │ from the map, │ │
│ │ what to │ creates OpenSpec │ │
│ │ work on │ changes │ │
│ │ next │ │ │
│ └─────┬──────┘ │ │
│ │ │ │
└────────────────────────┼─────────────────────────┼──────────────┘
│ │
story specs │ status + cost flow up │
flow down │ │
▼ │
┌──────────────────────────────────────────────────┼──────────────┐
│ │ │
│ EXECUTION PLANE (agents build it) │ │
│ │
│ Agents receive precise specs, work in isolation, │
│ produce PRs. They don't decide what to build. │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ │ /aep-design │───►│ /aep-launch │───►│ /aep-build │───►│ /aep-wrap │ │
│ │ │ │ │ │ │ │ │ │
│ │ refine │ │ spawn │ │ implement│ │ archive │ │
│ │ the spec │ │ agent │ │ + test │ │ + update│ │
│ │ │ │ │ │ + PR │ │ status │ │
│ └──────────┘ └──────────┘ └──────────┘ └─────────┘ │
│ │
│ (repeat per story — multiple stories run in parallel) │
│ │
└─────────────────────────────────────────────────────────────────┘
```
![AEP mental model: control plane and execution plane](assets/aep-mental-model.png)

> This is the conceptual split. The control plane also has **specialized steps** this view omits — `/aep-model` (noun-first Object Map, UI-facing only), `/aep-calibrate` (human alignment on `.5` layers), `/aep-validate`, and `/aep-watch`. They appear in the detailed [Product Context](#1-product-context--the-persistent-map) flow below.

**Agents don't talk to each other.** They communicate through structured artifacts — context documents, story specs, interface contracts, signal files. The harness coordinates everything. This is a production system design, not a chatroom-style agent swarm.

Expand Down Expand Up @@ -446,39 +398,12 @@ Each plugin implements one layer of the mental model.

Captures the "what and why" of the entire product in a single `product-context.yaml` — committed to git, versioned, and machine-parseable.

```
/aep-envision /aep-map /aep-reflect
│ │ │
▼ ▼ ▼
Opportunity Brief System Map Classify feedback:
"should we build this?" "modules + interfaces" bug → fix story
│ │ refinement → next layer
▼ ▼ discovery → update map
Context Document Story Graph shift → re-envision
"what exactly to build, "layered work items, │
for whom, within waves + slices" │
what constraints" │ │
│ ▼ │
│ Agent Topology │
│ "roles + contracts" │
│ │ │
└───────────────┬───────────────┘ │
│ │
▼ │
/aep-dispatch │
"pick next story, ◄─────────────────────────┘
create OpenSpec change, (new stories feed back
route to /aep-design" into the dispatch queue)
│
├─── integer layer ──► /aep-design → /aep-launch → /aep-build → /aep-wrap
│
└─── .5 alignment layer ──► /aep-calibrate → human aligns
→ /aep-calibrate capture
→ /aep-dispatch → /aep-launch → /aep-build → /aep-wrap
```
![AEP product context flow](assets/aep-product-context-flow.png)

All sections live in one `product-context.yaml` file — opportunity, product, architecture, stories (with state machine), topology, layer gates, cost tracking, and a semantic changelog.

> **`/aep-model` is UI-facing only** (the noun-first **Object Map** step shown above). It auto-drafts from the story map, takes a short human approval, then governs object structure — so build agents stop inventing one-step-one-screen task-wizard UIs. Stored under `product/` (`object-model.yaml` + `maps/<capability>/object-map.yaml`), gated by dispatch/launch. Background: [docs/research/ooux-object-modeling.md](docs/research/ooux-object-modeling.md).

**Why this exists:** Without a product-level map, each feature is designed in isolation. Agents build incompatible pieces. Module boundaries are implicit. The YAML makes the whole system visible, machine-readable, and git-versioned before any code is written.

### 2. Feature Lifecycle — the execution cycle
Expand Down Expand Up @@ -663,7 +588,7 @@ These aren't rules we invented — they're patterns extracted from Anthropic's e

## Getting Started

**Brand new to AEP?** Start with the [Orientation Guide](docs/orientation.md) for a 10-minute tour of the mental models, the 17 skills, and the four paths — then run `/aep-onboard`.
**Brand new to AEP?** Start with the [Orientation Guide](docs/orientation.md) for a 10-minute tour of the mental models, the 19 skills, and the four paths — then run `/aep-onboard`.

**New to this plugin?**

Expand Down Expand Up @@ -721,6 +646,7 @@ Generate a dimension-specific brief, explore or discuss, capture decisions for a
| ---------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| `/aep-envision` | product-context | Opportunity brief + context document |
| `/aep-map` | product-context | System map + story graph + agent topology |
| `/aep-model` | product-context | Object-first UI structure (OOUX/ORCA Object Map) for UI products |
| `/aep-dispatch` | product-context | Pick next story + create OpenSpec change |
| `/aep-calibrate` | product-context | Human alignment checkpoint for any quality dimension |
| `/aep-reflect` | product-context | Classify feedback + update context |
Expand Down
Binary file added assets/aep-mental-model.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/aep-product-context-flow.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading