Skip to content

feat(aep): human-alignment skill v3.3.0 — one-page project brief from product-context.yaml #29

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 13 commits into from
Jul 27, 2026
Merged

feat(aep): human-alignment skill v3.3.0 — one-page project brief from product-context.yaml #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
7f08bc2
feat(aep): human-alignment skill v3.3.0 — one-page project brief from…
memorysaver Jul 25, 2026
70e82f4
test(aep): independent routing probe for the 23-skill corpus
memorysaver Jul 25, 2026
2cf2b31
docs(aep): human-alignment revision 8 — Engineering is prospective-st…
memorysaver Jul 25, 2026
51ffc1c
feat(aep): implement revision 8 — measured concept binding, prospecti…
memorysaver Jul 25, 2026
b81f6a0
docs(aep): human-alignment revision 9 — completeness by construction
memorysaver Jul 25, 2026
b67e256
feat(aep): implement D9 — census, claim-level audit, predicates, cove…
memorysaver Jul 25, 2026
68ea7f7
docs(aep): record gen/eval round 2 — still FAIL, different failure mode
memorysaver Jul 25, 2026
f27da0c
fix(aep): close the four pipeline defects round 2 found
memorysaver Jul 25, 2026
15903e1
docs(aep): human-alignment revision 10 — the unit is the clock, not t…
memorysaver Jul 27, 2026
18afa46
feat(aep): converge on revision 10 — add the pulse, fix the one-ask o…
memorysaver Jul 27, 2026
c493fc0
docs(aep): regenerate the looplia example at a28fec13 with all three …
memorysaver Jul 27, 2026
8428a5b
feat(aep): implement D11 — detectors move to /aep-validate, the brief…
memorysaver Jul 27, 2026
7a7a2df
docs(aep): ship v3.3.0 as the pulse; mark the brief unproven
memorysaver Jul 27, 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
9 changes: 8 additions & 1 deletion .claude-plugin/marketplace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"email": "mho@looplia.run"
},
"metadata": {
"version": "3.2.1",
"version": "3.3.0",
"description": "Skills for product planning, project scaffolding, and agentic development workflows."
},
"plugins": [
Expand Down Expand Up @@ -49,6 +49,13 @@
"./skills/agentic-development-workflow/git-ref"
]
},
{
"name": "human-alignment",
"description": "Project pulse from product-context.yaml: where it stands, what is owed to a human and for how long, and what changed since you last looked.",
"source": "./",
"strict": false,
"skills": ["./skills/human-alignment"]
},
{
"name": "patterns",
"description": "Reusable design patterns: gen/eval, executor abstraction, autopilot orchestration, dynamic workflows, workflow-feedback, design-lens (HCI theory + heuristic health-check).",
Expand Down
2 changes: 1 addition & 1 deletion .oxfmtrc.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
"ignorePatterns": []
"ignorePatterns": ["docs/human-alignment/example-*/**"]
}
68 changes: 68 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,74 @@ bug fixes → **patch**; removing or breaking a skill contract → **major**.
> `/envision`, `/dispatch`, `/reflect`, …), which records product-state history
> for that project. See [`docs/glossary.md`](docs/glossary.md).

## [3.3.0] - 2026-07-27

`/aep-human-alignment` — a project pulse. One command answers where a project
stands, what is owed to a human and for how long, and what changed since you
last looked, derived from `product-context.yaml`.

The design went through ten revisions and two independent generator/evaluator
rounds, both of which failed the artifact it originally set out to produce. What
ships is what survived that: the deterministic half.

### Added

- **`skills/human-alignment/`** — a standalone top-level skill, a fifth
marketplace plugin, emitting on three clocks rather than one:
- **The fact plane** (`derive.mjs` + `census.mjs` + `facts.schema.json`) —
every number the surface can state, derived from the plan file and git,
validated against its own schema. `census.mjs` classifies every populated
path in the consumer's plan file as derived / ignored-with-a-reason /
unhandled, so what the tooling cannot see is a number rather than a
surprise.
- **The pulse** (`pulse.mjs`) — the read-time answer to _what happened since I
last looked_. It writes nothing, asserts nothing, and deals in events rather
than states. Four sections: obligations with their age, transitions since
your cursor, what needs a human, and open work that has stopped moving.
- **The deterministic architecture pipeline** (`scan-workspace.mjs` →
`arch-rules.mjs` → `receipt-consumer.mjs`) — the real package topology, with
concepts bound to code units by measurement from the work record, rendered
through archify's layout gates and repaired only by its own receipts.
- **Two framework specs** in `skills/product-context/_shared/references/` —
`attention-set.md` (what needs a human, its priority order, per-predicate
schema tolerance) and `drift-facts.md` (where reality drifted).

### Changed

- **`/aep-validate` gains a blocking coherence precheck.** Five plan-file
defects that want an action rather than a reader — completed work under a gate
recorded as never started, an undefined gate status, a roll-up that disagrees
with the record it summarizes, a module used but never declared, and fields a
consumer invented — now run mechanically before any agent is spawned, and
fail. They were previously narrated in a document while nothing stopped.
- **`scripts/build-skills.sh` materializes shared resources into top-level
skills and shared `scripts/`**, on the same per-file rule it has always used
for references. The coherence detector is shared rather than copied: two
copies of a drift detector drift.
- **Pre-commit hooks no longer fail a docs-only commit.** oxlint and oxfmt error
rather than no-op when handed nothing they handle; both now carry a glob and
oxfmt guards on the post-filter set.

### Not yet ready

- **The one-page HTML brief (emission 3) ships unproven and is documented as
such.** Two independent evaluations failed it — not on machinery, which
passes, but on prose asserting more than the facts carried. Its per-layer
regeneration trigger is unbuilt; today it generates per invocation, which the
decision doc identifies as the central design error. Findings and a generated
example are committed at `docs/human-alignment/example-looplia/` as evidence,
not as a model to copy. Use the pulse.

### Notes

- Only a `passed` gate yields an unchipped capability; `scripted_passed` appears
solely under an EXP chip naming the acceptance run that would settle it, and a
gate whose sign-off was withdrawn yields neither.
- A roll-up field being zero is a statement about the roll-up, not about the
data. Spend derives from `stories[].cost_usd`; the concept-to-code binding
derives from `stories[].module` × `files_affected`.
- Consumers must re-pin to `@v3.3.0` before `/aep-human-alignment` is available.

## [3.2.1] - 2026-07-18

Patch: the `secret_scan` example in the scaffolded `policy.md` named
Expand Down
50 changes: 26 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,7 @@ The `skills` CLI selects by skill name (there's no "group" flag). The groups map
| **Product** (product-context) | `aep-envision`, `aep-map`, `aep-model`, `aep-dispatch`, `aep-validate`, `aep-calibrate`, `aep-reflect`, `aep-watch` |
| **Setup** (project-setup) | `aep-onboard`, `aep-scaffold`, `aep-e2e-skill-scaffolding` |
| **Patterns** (patterns) | `aep-gen-eval`, `aep-executor`, `aep-autopilot`, `aep-workflow`, `aep-workflow-feedback`, `aep-design-lens` |
| **Alignment** (human-alignment) | `aep-human-alignment` |

> **Releasing:** bumping `metadata.version` in `.claude-plugin/marketplace.json` must come with a matching [CHANGELOG.md](CHANGELOG.md) entry in the same PR (move the `[Unreleased]` notes under the new `[X.Y.Z] - DATE` heading), and a `vX.Y.Z` git tag on merge to `main`.

Expand Down Expand Up @@ -626,30 +627,31 @@ Generate a dimension-specific brief, explore or discuss, capture decisions for a

## All Skills

| Skill | Plugin | Purpose |
| ---------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `/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-validate` | product-context | Generator/evaluator validation of any AEP artifact |
| `/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 |
| `/aep-watch` | product-context | Ingest telemetry/errors → auto-file stories (self-feeding loop) |
| `/aep-onboard` | project-setup | Verify tools + install plugins |
| `/aep-scaffold` | project-setup | Scaffold monorepo + initialize OpenSpec; idempotent audit→converge for existing projects |
| `/aep-e2e-skill-scaffolding` | project-setup | Generate/upgrade the canonical BDD layer-gate e2e-test skill |
| `/aep-design` | agentic-development-workflow | Explore + propose + review a feature |
| `/aep-launch` | agentic-development-workflow | Spawn workspace (Claude bg subagents/sessions; Codex subagents/exec; tmux when pinned) + optional evaluator |
| `/aep-build` | agentic-development-workflow | Implement → test → PR → merge |
| `/aep-wrap` | agentic-development-workflow | Archive + cleanup + suggest reflect |
| `/aep-git-ref` | agentic-development-workflow | AEP git + worktree conventions (on-demand) |
| `/aep-gen-eval` | patterns | Generator/evaluator separation for honest validation |
| `/aep-executor` | patterns | Host-agnostic backend for spawning/steering workspace agents |
| `/aep-autopilot` | patterns | Autonomous dispatch-launch-monitor-wrap loop via `/loop` |
| `/aep-workflow` | patterns | Dynamic workflows — author a custom multi-agent harness for a task (+ sub-pattern catalog) |
| `/aep-workflow-feedback` | patterns | Capture + review process learnings between downstream projects and AEP |
| `/aep-design-lens` | patterns | Theory-grounded design guideline + heuristic health-check (HCI/design-theory catalog + task/data lens selection) |
| Skill | Plugin | Purpose |
| ---------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `/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-validate` | product-context | Generator/evaluator validation of any AEP artifact |
| `/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 |
| `/aep-watch` | product-context | Ingest telemetry/errors → auto-file stories (self-feeding loop) |
| `/aep-onboard` | project-setup | Verify tools + install plugins |
| `/aep-scaffold` | project-setup | Scaffold monorepo + initialize OpenSpec; idempotent audit→converge for existing projects |
| `/aep-e2e-skill-scaffolding` | project-setup | Generate/upgrade the canonical BDD layer-gate e2e-test skill |
| `/aep-design` | agentic-development-workflow | Explore + propose + review a feature |
| `/aep-launch` | agentic-development-workflow | Spawn workspace (Claude bg subagents/sessions; Codex subagents/exec; tmux when pinned) + optional evaluator |
| `/aep-build` | agentic-development-workflow | Implement → test → PR → merge |
| `/aep-wrap` | agentic-development-workflow | Archive + cleanup + suggest reflect |
| `/aep-git-ref` | agentic-development-workflow | AEP git + worktree conventions (on-demand) |
| `/aep-gen-eval` | patterns | Generator/evaluator separation for honest validation |
| `/aep-executor` | patterns | Host-agnostic backend for spawning/steering workspace agents |
| `/aep-autopilot` | patterns | Autonomous dispatch-launch-monitor-wrap loop via `/loop` |
| `/aep-workflow` | patterns | Dynamic workflows — author a custom multi-agent harness for a task (+ sub-pattern catalog) |
| `/aep-workflow-feedback` | patterns | Capture + review process learnings between downstream projects and AEP |
| `/aep-design-lens` | patterns | Theory-grounded design guideline + heuristic health-check (HCI/design-theory catalog + task/data lens selection) |
| `/aep-human-alignment` | human-alignment | Project pulse from `product-context.yaml` — where it stands, what is owed to a human and for how long, what changed since you last looked |

Launches are **native-first** with **hub-and-spoke human gates** — see
[Launch modes](#launch-modes--native-first-executor-backends) and
Expand Down
Loading
Loading