You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
SAN-1272 — Make MDE AI coding agents choose the right skills, workflow, and checks - #45
This PR standardizes how coding agents work on MDE AI.
Real-world example: if a developer asks, “Fix a Supabase RLS policy used by a Mastra workflow and update the approval UI,” the agent should not load every skill or guess the owner. It should route the work to the smallest correct set of skills, run the right tests, review the diff, and require stronger proof for high-risk changes.
The skill architecture is strong and the exact PR head passes the MDE skill/vendor validators, but the PR still has merge blockers: Floor CI is red, committed bootstrap files still contain stale pre-rename skill names, real model routing/behavior tests have not executed, and CodeRabbit skipped the PR because it contains 401 files.
🟠 CodeRabbit skipped — 401 files exceeds its 100-file limit
Developer workflow / user journey
flowchart TD
U[Developer request] --> Q{Single clear owner?}
Q -->|Yes| D[Use the directly relevant skill]
Q -->|No / multi-system| R[using-mde-skills]
R --> C[Classify S0-S4 and choose one primary owner]
C -->|S0-S1| D
C -->|S2-S4 substantial work| T[tasks orchestrator]
T --> S[Load only affected stack/domain skills]
D --> V[Implement smallest safe change]
S --> V
V --> TEST[tdd / testing]
TEST --> CR[code-review]
CR --> H{High risk or Done claim?}
H -->|Yes| TV[task-verifier independent gate]
H -->|No| PR[PR / handoff]
TV -->|Pass| PR
TV -->|Fail| FIX[Return to owning workflow]
FIX --> V
Loading
Portable agent setup
flowchart LR
REPO[MDE AI repo] --> AG[AGENTS.md\nportable project rules]
REPO --> CL[CLAUDE.md\nClaude-specific rules]
REPO --> SK[.claude/skills/\ncanonical skill library]
CL --> CC[Claude Code]
SK --> CC
AG --> OC[OpenCode]
SK --> OC
AG --> CU[Cursor]
SK --> CU
AG --> CX[Codex / other agents]
SK --> ROUTE[using-mde-skills]
ROUTE --> TASKS[tasks]
TASKS --> OWNERS[stack + domain owners]
Loading
Claude Code uses .claude/skills/ natively. OpenCode and Cursor also support Claude-compatible project skills. AGENTS.md provides the small tool-neutral bootstrap instead of maintaining four copies of the skill library.
What changed
Core workflow
modernized tasks, task-verifier, wireframe, and mermaid-diagrams
added using-mde-skills as a router only
kept tasks as the substantial implementation orchestrator
added shared prompting, outcome, subagent, and skill-authoring standards
added deterministic validators for skill structure, routing references, task trackers, vendor pins, and upstream drift
added AGENTS.md for portable repo-level guidance
corrected the Claude session-start architecture and removed broken active skill aliases
Canonical stack skills
copilotkit
mastra
supabase
gemini
stripe
nextjs
maps
cloudinary
Canonical domain skills currently in scope
events
real-estate
Do not create placeholder domain skills merely to fill a list. Add restaurants, venues, trips, partners, or ecommerce only when there is real project-specific workflow knowledge worth preserving.
Skills and MCPs/tools to use
Need
Best owner
Ambiguous or multi-system request
using-mde-skills
Substantial implementation
tasks
Unknown failure/root cause
systematic-debugging
Test-first regression fix
tdd
Verification strategy
testing
Current official API/framework research
research + Context7 / official docs
Existing PR/diff review
code-review
Done / merge / production claim
task-verifier
Architecture or journey diagram
mermaid-diagrams
GitHub PR, exact diff, CI
GitHub connector
Linear scope/progress/evidence
Linear connector
Current library documentation
Context7
Exact local files/commands/commit proof
Remote Desktop Commander
Efficiency rule: simple task → direct skill. Use the router only when ownership is unclear or multiple systems are involved. Subagents are optional accelerators, not mandatory ceremony.
Application tech stack context
This PR changes the developer-agent control plane, not the customer application runtime.
No customer-facing screen implementation is changed by this PR. It changes repository instructions, skill packages, references, validators, and session bootstrap.
Current app surfaces that must continue to work after merge include /, /chat, /events, /rentals, /restaurants, /cafes, /nightlife, /venues, /host/*, /me/tickets, /trips, and /partners/*. The existing CI production build successfully discovers these routes.
Forensic audit findings
Priority
Finding
Why it matters
Required action
🔴 Blocker
Floor CI is red at npm audit --audit-level=critical
A merge-ready PR cannot claim green production gates
Resolve or formally isolate the critical dependency finding, then rerun Floor
🔴 Blocker
AGENTS.md and CLAUDE.md at the PR head still reference mde-maps / mde-real-estate; CLAUDE.md also says events and stripe are not active even though the canonical skills now exist
Fresh sessions can receive contradictory routing instructions
Update both bootstraps to the canonical names and rerun validators/fresh-session proof
🔴 Blocker
Real routing and vendor behavior evals have not executed
JSON definitions prove test design, not agent behavior
Run 10–15 real routing prompts + one real CopilotKit/Mastra/Supabase/Gemini behavior case
🟠 High
CodeRabbit skipped the PR because 401 files exceeds its review limit
Independent automated review coverage is incomplete
Split review units or perform an independent exact-head review before merge
🟠 High
Canonical maps/SKILL.md still contains stale/broken project links and legacy assumptions; validator reports active Maps warnings
The active skill can direct an agent to missing paths
Repair the active Maps references first; leave deep historical warning cleanup incremental
🟡 Medium
84 legacy/reference warnings remain
Noise can hide new reference regressions
Reduce gradually; do not block the entire core on historical mirrors
Move low-frequency detail into references when next touched
🟡 Existing repo debt
Floor audit reports 51 vulnerabilities, including 1 critical; PR does not modify package.json/lockfile
Mostly pre-existing, but still a repository merge gate
Track/fix separately if not safe to solve in this PR; do not hide the red gate
Current dependency-security blocker
Floor CI reaches lint, typecheck, production build, Vitest, and Mastra successfully, then fails on the audit gate. The audit currently reports 51 vulnerabilities: 17 low, 18 moderate, 15 high, 1 critical. The critical set includes the installed Next.js 16.2.6; npm reports a newer Next.js release outside the current declared range as a possible fix.
This PR does not modify dependency manifests, so the dependency issue should not be silently folded into the skill refactor. The efficient path is to fix it in a focused dependency/security change or explicitly establish the correct merge policy, then rerun the exact PR head.
Scores
Area
Score
Architecture / ownership model
92/100
Skill organization / progressive disclosure
88/100
Vendor provenance / pinned-reference design
92/100
Portability design
88/100
Routing definition quality
88/100
Bootstrap consistency at current PR head
58/100
Real executed eval proof
35/100
Reviewability
45/100
CI / security readiness
45/100
Current merge readiness
58/100 — blocked
The Linear checklist can still be 88% implementation-complete while merge readiness is lower: implementation progress and release evidence are different measurements.
Fastest safe path to finish
flowchart TD
A[PR #45 current head] --> B[Fix CLAUDE.md + AGENTS.md canonical names]
B --> C[Repair active Maps broken/stale references]
C --> D[Run exact skill + vendor validators]
D --> E[Run 10-15 real routing prompts]
E --> F[Run 4 vendor behavior cases]
F --> G[Run S0-S4 fresh-session certification]
G --> H{Independent review available?}
H -->|PR still too large| I[Split review units or perform exact-head manual review]
H -->|Yes| J[Resolve red Floor security gate]
I --> J
J --> K[All required checks green]
K --> L[Merge]
Loading
Do not add more orchestration features before these gates pass.
Pre-merge production-readiness checklist
Already verified
Exact PR head identified: 398bf626daf35635c6b8c0ff7891e8b960497e23
674c61d — modernize MDE task design and verification skills
ca80963 — checkpoint portable MDE skill foundation
398bf62 — normalize canonical stack and domain skills
Review note on PR size
The existing commits are useful checkpoints, but simply splitting by commit is not enough: the three slices touch roughly 48, 244, and 130 files. If automated review coverage is required, split by review responsibility instead of blindly by commit — core router/bootstrap/validators, vendor snapshots/wrappers, and large domain/reference migrations. That is faster to review and safer than rewriting the whole implementation.
amoai-tech
changed the title
SAN-1272 · MDE-SKILLS-001 — Canonical skills and portable orchestration foundation
SAN-1272 — One shared MDE skill system for Claude Code, Cursor, OpenCode & Codex
Sep 15, 2026
amoai-tech
changed the title
SAN-1272 — One shared MDE skill system for Claude Code, Cursor, OpenCode & Codex
SAN-1272 — Make MDE AI coding agents choose the right skills, workflow, and checks
Sep 15, 2026
Superseded by the staged SAN-1274/SAN-1273 landing sequence: PRs #47, #48, #49, #50 and #52.
The useful canonical skills, bootstrap, security, routing, and live-certification work has been extracted into smaller independently verified PRs.
PR #45 should not be merged because it contains the older large orchestration design and would reintroduce superseded/conflicting files.
The PR #45 branch/history is being retained temporarily as forensic/recovery evidence; local historical branches are not being deleted as part of this closure.
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
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.
amoai-tech
changed the title
What this PR does
This PR standardizes how coding agents work on MDE AI.
Real-world example: if a developer asks, “Fix a Supabase RLS policy used by a Mastra workflow and update the approval UI,” the agent should not load every skill or guess the owner. It should route the work to the smallest correct set of skills, run the right tests, review the diff, and require stronger proof for high-risk changes.
Linear task: https://linear.app/amo100/issue/SAN-1272/mde-skills-001-build-canonical-skills-subagent-orchestration-for-mde
Evidence index: https://linear.app/amo100/document/san-1272-skills-orchestration-evidence-index-45e1d463c91a
Status at a glance
398bf626daf35635c6b8c0ff7891e8b960497e23npm audit --audit-level=criticalDeveloper workflow / user journey
flowchart TD U[Developer request] --> Q{Single clear owner?} Q -->|Yes| D[Use the directly relevant skill] Q -->|No / multi-system| R[using-mde-skills] R --> C[Classify S0-S4 and choose one primary owner] C -->|S0-S1| D C -->|S2-S4 substantial work| T[tasks orchestrator] T --> S[Load only affected stack/domain skills] D --> V[Implement smallest safe change] S --> V V --> TEST[tdd / testing] TEST --> CR[code-review] CR --> H{High risk or Done claim?} H -->|Yes| TV[task-verifier independent gate] H -->|No| PR[PR / handoff] TV -->|Pass| PR TV -->|Fail| FIX[Return to owning workflow] FIX --> VPortable agent setup
flowchart LR REPO[MDE AI repo] --> AG[AGENTS.md\nportable project rules] REPO --> CL[CLAUDE.md\nClaude-specific rules] REPO --> SK[.claude/skills/\ncanonical skill library] CL --> CC[Claude Code] SK --> CC AG --> OC[OpenCode] SK --> OC AG --> CU[Cursor] SK --> CU AG --> CX[Codex / other agents] SK --> ROUTE[using-mde-skills] ROUTE --> TASKS[tasks] TASKS --> OWNERS[stack + domain owners]Claude Code uses
.claude/skills/natively. OpenCode and Cursor also support Claude-compatible project skills.AGENTS.mdprovides the small tool-neutral bootstrap instead of maintaining four copies of the skill library.What changed
Core workflow
tasks,task-verifier,wireframe, andmermaid-diagramsusing-mde-skillsas a router onlytasksas the substantial implementation orchestratorAGENTS.mdfor portable repo-level guidanceCanonical stack skills
copilotkitmastrasupabasegeministripenextjsmapscloudinaryCanonical domain skills currently in scope
eventsreal-estateDo not create placeholder domain skills merely to fill a list. Add
restaurants,venues,trips,partners, orecommerceonly when there is real project-specific workflow knowledge worth preserving.Skills and MCPs/tools to use
using-mde-skillstaskssystematic-debuggingtddtestingresearch+ Context7 / official docscode-reviewtask-verifiermermaid-diagramsEfficiency rule: simple task → direct skill. Use the router only when ownership is unclear or multiple systems are involved. Subagents are optional accelerators, not mandatory ceremony.
Application tech stack context
This PR changes the developer-agent control plane, not the customer application runtime.
16.2.6, React19.2.1, CopilotKit1.55.2, shadcn, Tailwind CSS 4, Google Maps@ai-sdk/google 2.0.74^2.106.1, Supabase SSR, Postgres, RLS, Next.js Route Handlers@vis.gl/react-google-maps, Google Places, MarkerClusterer4.1.6, Playwright1.60.0, GitHub ActionsFrontend / backend / screens
No customer-facing screen implementation is changed by this PR. It changes repository instructions, skill packages, references, validators, and session bootstrap.
Current app surfaces that must continue to work after merge include
/,/chat,/events,/rentals,/restaurants,/cafes,/nightlife,/venues,/host/*,/me/tickets,/trips, and/partners/*. The existing CI production build successfully discovers these routes.Forensic audit findings
npm audit --audit-level=criticalAGENTS.mdandCLAUDE.mdat the PR head still referencemde-maps/mde-real-estate;CLAUDE.mdalso sayseventsandstripeare not active even though the canonical skills now existmaps/SKILL.mdstill contains stale/broken project links and legacy assumptions; validator reports active Maps warningsmde-worktree-pr-flow/SKILL.mdis 519 linespackage.json/lockfileCurrent dependency-security blocker
Floor CI reaches lint, typecheck, production build, Vitest, and Mastra successfully, then fails on the audit gate. The audit currently reports 51 vulnerabilities: 17 low, 18 moderate, 15 high, 1 critical. The critical set includes the installed Next.js
16.2.6; npm reports a newer Next.js release outside the current declared range as a possible fix.This PR does not modify dependency manifests, so the dependency issue should not be silently folded into the skill refactor. The efficient path is to fix it in a focused dependency/security change or explicitly establish the correct merge policy, then rerun the exact PR head.
Scores
The Linear checklist can still be 88% implementation-complete while merge readiness is lower: implementation progress and release evidence are different measurements.
Fastest safe path to finish
flowchart TD A[PR #45 current head] --> B[Fix CLAUDE.md + AGENTS.md canonical names] B --> C[Repair active Maps broken/stale references] C --> D[Run exact skill + vendor validators] D --> E[Run 10-15 real routing prompts] E --> F[Run 4 vendor behavior cases] F --> G[Run S0-S4 fresh-session certification] G --> H{Independent review available?} H -->|PR still too large| I[Split review units or perform exact-head manual review] H -->|Yes| J[Resolve red Floor security gate] I --> J J --> K[All required checks green] K --> L[Merge]Do not add more orchestration features before these gates pass.
Pre-merge production-readiness checklist
Already verified
398bf626daf35635c6b8c0ff7891e8b960497e23validate-skills.pypasses: 27 core skills / 42 routing definitionsvalidate-vendor-skills.pypasses: 4 pinned vendor wrappers / local hashes verifiedMust pass before merge
CLAUDE.mdandAGENTS.mdmapsskill links/legacy path assumptions that can misroute current worktask-verifierSuccess criteria
The skill platform is ready when:
CLAUDE.md,AGENTS.md, routing, registry, and skill folders all use the same canonical names;Post-merge actions
mainto the exact merge SHAmainmainOfficial references used for this review
Skill authoring / agent behavior
Official vendor skill sources pinned by this PR
MDE source of truth
Commits in this PR
674c61d— modernize MDE task design and verification skillsca80963— checkpoint portable MDE skill foundation398bf62— normalize canonical stack and domain skillsReview note on PR size
The existing commits are useful checkpoints, but simply splitting by commit is not enough: the three slices touch roughly 48, 244, and 130 files. If automated review coverage is required, split by review responsibility instead of blindly by commit — core router/bootstrap/validators, vendor snapshots/wrappers, and large domain/reference migrations. That is faster to review and safer than rewriting the whole implementation.