agent-easy-framework 0.0.3__tar.gz

agent_easy_framework-0.0.3/.cursor/rules/skill-orchestrator-gate.mdc

@@ -0,0 +1,51 @@
+---
+description: >-
+  Mandatory completion gate — run skill-orchestrator after every code change
+  before marking a task done.
+alwaysApply: true
+---
+
+# Skill orchestrator completion gate
+
+After **any code change** in this repo, follow [skill-orchestrator](../skills/skill-orchestrator/SKILL.md) **before** telling the user the task is done.
+
+## Required flow
+
+```
+implement → skill-orchestrator → close report (Ready to ship: YES) → then done
+```
+
+## Triggers
+
+Run the orchestrator when you edit:
+
+- `src/`, `tests/`, `tools/`
+- `*.py`, generator, or templates under `create_agent_server/`
+
+If there is no git diff yet, validate the files changed in the session.
+
+## Blocks close
+
+Do **not** mark the task complete while any of these fail:
+
+- code-smell-review (must_fix > 0)
+- onboarding-validation Judge (when onboarding surfaces changed)
+- adoption-validation P0 escalations (when release/adoption pipeline)
+- `make check` or `make test`
+
+## Skip (rare)
+
+Skip only when:
+
+- **Question-only** or read-only work — no files changed
+- User **explicitly** opts out for this task — note `SKIPPED` + reason in close report
+
+## Minimum pipeline
+
+Most code-only changes → **pipeline A**: smell review → `make check` → `make test`.
+
+Docs/generator/examples → **pipeline B**. Pre-release → **pipeline C**. See [pipelines.md](../skills/skill-orchestrator/pipelines.md).
+
+## Close report
+
+Before saying done, produce the orchestrator close report from the skill with `Ready to ship: YES`.

agent_easy_framework-0.0.3/.cursor/skills/adoption-validation/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: adoption-validation
+description: >-
+  Docs-only multi-agent adoption test: a critical platform team with no prior
+  context tries to scaffold and run an MCP server using only published docs.
+  Use before releases, after README/CLI/generator changes, or when validating
+  whether real teams can adopt agent-easy. Findings that need fixes must
+  escalate through the onboarding-validation skill — never fix from adoption
+  reports alone.
+---
+
+# Adoption Validation
+
+Simulates a **skeptical platform team** adopting `agent-easy` for the first time. Sub-agents get **no conversation context** and **no source access** — only documented entry points. They must scaffold, configure, and invoke tools exactly as a PyPI user would.
+
+If they find problems, **do not patch the framework from this skill**. Escalate through [onboarding-validation](../onboarding-validation/SKILL.md) so each issue is proven `GENUINE_UX_CONFUSION`, not team error.
+
+## When to Run
+
+- Before PyPI release or major doc/CLI changes
+- After changing README quickstart, `agent-easy mcp` flags, or generator output
+- User asks to "test adoption", "can a team use this from docs", or "run the adoption team"
+- After adoption FAIL — only **after** onboarding-validation confirms fixes
+
+## Adoption bar
+
+The team is **critical and time-poor**. They will bounce if:
+
+- Quickstart fails on first copy-paste
+- Docs contradict each other (README vs generated README vs CLI output)
+- They must read `src/` to succeed
+- Surfaces are confused (in-process vs MCP HTTP vs ops REST)
+- Generate-time flags do not match default runtime profile without explanation
+
+**Verdict scale:**
+
+| Verdict | Meaning |
+|---------|---------|
+| **ADOPT** | Team would standardize on this from docs alone |
+| **ADOPT_WITH_FRICTION** | Works but docs/process need polish (escalate items) |
+| **REJECT** | Team would abandon or fork; block release until resolved |
+
+## Roles (all docs-only)
+
+| Agent | Persona | Must NOT |
+|-------|---------|----------|
+| **Platform engineer** | Owns the golden path; runs scaffold + setup | Read `src/`, `generator.py`, or prior chat |
+| **Integrator** | Wires MCP clients; runs example flows | Modify framework source |
+| **Adoption critic** | Staff engineer evaluating build vs buy | Soften findings; recommend architecture rewrites |
+
+Each agent reports **PASS/FAIL**, exact commands, exact output, and **blockers** with severity (P0/P1/P2).
+
+## Allowed documentation
+
+Agents may read **only**:
+
+| Doc | When |
+|-----|------|
+| `README.md` | Quickstart, flags, journey |
+| `GOLDEN_PATH.md` | Only if README points there or a step fails |
+| Generated `<project>/README.md` | After scaffold |
+| Generated `<project>/examples/README.md` | After scaffold |
+| CLI `--help` output | Flag discovery |
+
+**Forbidden:** `src/`, `tests/`, `generator.py`, conversation history, onboarding-validation reports from prior turns (unless orchestrator passes a **minimal** judge verdict for re-test).
+
+## Workflow
+
+```
+Adoption team (parallel, docs-only, no context)
+        ↓
+Adoption lead synthesizes verdict + findings
+        ↓
+Any finding that implies a doc/CLI/generator fix?
+   NO  → close with verdict
+   YES → onboarding-validation (Junior → Judge → [Product])
+        ↓
+Product implements only GENUINE_UX_CONFUSION items
+        ↓
+Re-run adoption-validation until ADOPT or ADOPT_WITH_FRICTION
+```
+
+**Never skip onboarding-validation for UX fixes suggested by the adoption team.**
+
+## Phase 1 — Platform engineer
+
+**Prompt pattern (spawn with `Task`, `subagent_type: shell` or `generalPurpose`):**
+
+```
+You are a platform engineer on a critical team adopting agent-easy for the first time.
+You have NO prior context and must NOT read source code under src/ or tests/.
+
+Read ONLY README.md "Quickstart (no clone)" (and GOLDEN_PATH.md only if README sends you there).
+
+Goal: scaffold a minimal MCP server and reach `make example` success.
+
+Rules:
+- Use a fresh temp directory (mktemp)
+- Primary command: uvx agent-easy mcp <name>  (if not on PyPI, report BLOCKER and use
+  uv run agent-easy mcp <name> from repo root ONLY as pre-publish fallback — tag as INFRA)
+- Follow CLI printed next steps, then generated project README
+- Do NOT read src/
+- Report PASS/FAIL, commands, output snippets, P0/P1/P2 blockers, time estimate
+```
+
+**Pass:** `make setup` + `make example` returns pong without source reads.
+
+## Phase 2 — Integrator
+
+**Input:** Path to generated project from Phase 1 (orchestrator provides).
+
+**Prompt pattern:**
+
+```
+You are an integrator on the same critical adoption team. NO prior context. NO src/ reads.
+
+Read ONLY the generated project's README.md and examples/README.md.
+
+Goal: prove documented surfaces work:
+1. In-process: make example (if not already done)
+2. Ops REST: ./examples/smoke_ops.sh (if documented) — only while server running if docs say two terminals
+3. MCP HTTP: make run-http + make example-http — ONLY if project was generated with http transport
+
+If stdio-only project: confirm docs do NOT falsely advertise HTTP; note if team expected HTTP from parent README.
+
+Report PASS/FAIL per surface, confusion points, P0/P1/P2 blockers.
+Do NOT modify source files.
+```
+
+**Pass:** Every surface **documented for that project shape** works or is correctly absent.
+
+## Phase 3 — Adoption critic
+
+**Input:** Platform + Integrator reports (orchestrator provides).
+
+**Prompt pattern:**
+
+```
+You are a staff engineer deciding whether your org adopts agent-easy vs FastMCP or an internal template.
+You have NO prior context. You may read README.md, GOLDEN_PATH.md, and the two sub-agent reports only.
+
+Deliver:
+- Verdict: ADOPT | ADOPT_WITH_FRICTION | REJECT
+- Top 3 adoption risks (plain language)
+- Each finding: severity P0/P1/P2, classification:
+    NEEDS_ONBOARDING_VALIDATION — might require doc/CLI/generator fix
+    USER_ERROR — team should have read the doc
+    OUT_OF_SCOPE — valid feedback but not this product's promise
+- Explicit: would you approve this as your org's MCP standard today? yes/no and why
+
+Do NOT recommend rewriting core architecture to compensate for doc gaps.
+```
+
+## Phase 4 — Adoption lead (orchestrator)
+
+Synthesize the three reports:
+
+```markdown
+# Adoption Validation Report
+
+## Verdict
+ADOPT | ADOPT_WITH_FRICTION | REJECT
+
+## Team summary
+[2–3 sentences]
+
+## Flow matrix
+| Flow | Platform | Integrator | Notes |
+|------|----------|------------|-------|
+
+## Findings
+| ID | Severity | Classification | Finding | Owner |
+|----|----------|----------------|---------|-------|
+
+## Escalation to onboarding-validation
+[List only NEEDS_ONBOARDING_VALIDATION items — one line each]
+```
+
+## Escalation gate (mandatory)
+
+For each finding classified **NEEDS_ONBOARDING_VALIDATION**:
+
+1. **Stop** — do not implement from the adoption report alone
+2. **Run** [onboarding-validation](../onboarding-validation/SKILL.md):
+   - Junior reproduces the failure with docs only
+   - Judge classifies `GENUINE_UX_CONFUSION` vs `USER_ERROR`
+   - Product resolves only genuine items
+3. **Re-run adoption-validation** after fixes
+
+If Judge marks **USER_ERROR**, update the adoption report to **reject** that finding — the team was wrong, not the product.
+
+If Judge marks **GENUINE_UX_CONFUSION**, Product implements, then onboarding-validation judge PASS, then adoption-validation re-run.
+
+## Subagent dispatch
+
+Use `Task` tool. **Do not pass conversation history** to sub-agents. Pass only:
+
+- Allowed doc paths (absolute)
+- Generated project path (after scaffold)
+- Pre-publish note if `uvx` unavailable: `"PyPI not published; platform engineer may use uv run from <repo> as INFRA fallback"`
+
+Suggested order:
+
+1. Platform engineer — foreground
+2. Integrator — after scaffold path known (foreground; background if long-running server)
+3. Adoption critic — after 1+2 complete
+4. Orchestrator writes report + escalation list
+
+For HTTP flows, generate with:
+
+```bash
+uvx agent-easy mcp adopt-http-test --transports stdio,http
+```
+
+Run a **second** integrator pass on that project if parent README advertises HTTP.
+
+## Scenarios to cover
+
+| Scenario | Generate command | Proves |
+|----------|------------------|--------|
+| Default quickstart | `agent-easy mcp my-service` | README hero path |
+| Production-shaped | `--datasources neo4j --transports stdio,http --auth oidc` | Flagship example + secrets note |
+| HTTP integrator | `--transports stdio,http` | MCP HTTP + ops distinction |
+
+Minimum release bar: **default quickstart** scenario reaches **ADOPT** or **ADOPT_WITH_FRICTION** with zero P0 NEEDS_ONBOARDING_VALIDATION items open.
+
+## Quality gate after adoption PASS
+
+When verdict is ADOPT or ADOPT_WITH_FRICTION and no open escalations:
+
+```bash
+make sync-templates   # if generator or templates changed during fix loop
+make check
+make test
+```
+
+## Relationship to onboarding-validation
+
+| Skill | Question |
+|-------|----------|
+| **adoption-validation** | Would a **critical team** adopt this from docs? |
+| **onboarding-validation** | Can a **junior** copy-paste each integration flow? |
+
+Adoption is broader and stricter in tone. Onboarding is the **appeals court** for whether adoption findings deserve product changes.
+
+## Related skills
+
+- **[skill-orchestrator](../skill-orchestrator/SKILL.md)** — runs adoption last on release pipelines; manages escalation back to onboarding
+
+## Anti-patterns
+
+- Fixing docs/code directly from adoption critic without Judge confirmation
+- Giving sub-agents repo context or prior chat ("we just changed the CLI…")
+- Letting the team read `src/` when stuck — that hides doc gaps
+- REJECT verdict → rewrite architecture instead of fixing docs/onboarding
+- PASS adoption when `uvx` is documented but PyPI package is missing (tag INFRA P0, verdict at most ADOPT_WITH_FRICTION)
+- Skipping integrator because platform engineer already ran `make example`
+
+## Example orchestrator close
+
+```
+Adoption verdict: ADOPT_WITH_FRICTION
+Escalations: 1 (profile override unclear — NEEDS_ONBOARDING_VALIDATION)
+→ Running onboarding-validation on item #1…
+→ Judge: GENUINE_UX_CONFUSION → Product adds README note → onboarding PASS
+→ Re-run adoption-validation → ADOPT
+```

agent_easy_framework-0.0.3/.cursor/skills/code-smell-review/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: code-smell-review
+description: >-
+  Sub-agent gate that reviews diff hunks for code smells, comment noise,
+  over-defensive fallbacks, and assertiveness gaps. Invoked by
+  skill-orchestrator after every code change — do not mark work complete
+  without orchestrator PASS. Also use when the user asks for a smell review
+  directly.
+---
+
+# Code Smell Review
+
+Structured sub-agent workflow: parent implements → **reviewer sub-agent** inspects **diff hunks only** → parent fixes → repeat until reviewer **PASS**.
+
+The reviewer is isolated by design (fresh sub-agent, no conversation history). It reports findings; the parent applies fixes. **Do not mark work complete until the reviewer passes.**
+
+## When to Run
+
+Run via **[skill-orchestrator](../skill-orchestrator/SKILL.md)** after every code change (default path).
+
+Standalone (orchestrator bypass only if user explicitly opts out):
+
+- User asks to "review for smells", "check comments", or "run smell gate"
+
+## Roles
+
+| Agent | Role | Must NOT |
+|-------|------|----------|
+| **Parent** | Implement features, apply reviewer fixes | Skip the gate or dismiss findings without fixing |
+| **Smell reviewer** | Inspect diff hunks, return PASS/FAIL + findings | Edit files, see conversation history, rationalize parent choices |
+
+## Workflow
+
+```
+Parent implements → Smell reviewer (diff hunks) → [Parent fixes if FAIL] → repeat until PASS
+```
+
+### 1. Resolve diff scope
+
+Use **diff hunks only** — added/changed/removed lines in the current change set:
+
+```bash
+git diff HEAD          # unstaged + staged vs last commit
+git diff --cached      # staged only (if relevant)
+git diff origin/main...HEAD   # branch vs base, when preparing a PR
+```
+
+Pass the reviewer **only the diff output** (or equivalent patch). Do not include conversation rationale, task description, or "why I did this" unless a finding requires one line of file context to identify a symbol.
+
+### 2. Launch smell reviewer sub-agent
+
+Use `Task` with `subagent_type: generalPurpose`. Prompt must state:
+
+- **Read-only** — do not modify files
+- **Input** — the diff hunks only
+- **No bias** — do not assume the change is correct; flag real issues
+- **Output** — structured PASS/FAIL report (template below)
+
+Suggested model: mid-tier / fast reviewer model when available.
+
+### 3. Parent fixes findings
+
+For each `FAIL` finding classified **actionable**:
+
+- Fix in a separate pass (rename, delete comment, flatten nesting, remove fallback, etc.)
+- Re-run the reviewer on the **updated diff**
+- Repeat until **PASS**
+
+Skip only findings explicitly marked `false_positive` with one-line justification in the reviewer report. Do not bulk-ignore categories.
+
+### 4. Close the task
+
+After reviewer **PASS**, proceed with tests/lint as usual. The smell gate is a prerequisite to "done", not a substitute for `make check`.
+
+## Smell checklist
+
+Review **every added/changed hunk** for:
+
+### Comments
+
+- **Delete**: comments that narrate **what** the next lines do (`# increment counter`, `# return result`)
+- **Delete**: change narration (`# added for ticket X`, `# as requested`, `# TODO: clean up later` with no concrete constraint)
+- **Delete**: section-header comments (`# --- Setup ---`, `# ===== Helpers =====`)
+- **Delete**: comments restating obvious control flow (`# if user exists`, `# loop through items`)
+- **Keep**: non-obvious **why** — hidden constraints, subtle invariants, required workarounds, external API quirks
+- **Keep**: public API docstrings on exported surfaces; inline noise is the primary target
+
+**Test:** If deleting the comment loses no information a reader couldn't get from names and structure, flag it.
+
+### Naming
+
+- Flag identifiers that **require** a comment to understand (`data2`, `temp`, `handle_stuff`)
+- Prefer rename over comment
+
+### Complexity
+
+- Deep nesting (3+ levels): ternaries, if/else chains, nested switches
+- Functions doing too much (long blocks, multiple unrelated responsibilities)
+- God objects / modules accumulating unrelated helpers
+
+### Duplication
+
+- Copy-paste with slight variation that should unify
+- Inline logic that duplicates an existing utility in the codebase (note the existing symbol if visible from the hunk's imports/calls)
+
+### Over-defensive code
+
+- Redundant null/empty checks when types or callers already guarantee the value
+- Excessive try/except that swallows errors or hides bugs
+- Checks-before-use (existence probes) when operating and handling failure is clearer
+
+### Assertive over fallbacks
+
+- **Flag**: silent fallbacks when a required resource, config, path, or dependency is missing (`get(..., default)`, `or ""`, `if x else fallback_value`, broad except + continue)
+- **Prefer**: assert preconditions, raise explicit errors, fail fast with clear messages
+- **Exception**: user-facing optional features with documented defaults — still flag if the fallback hides misconfiguration
+
+### AI slop patterns
+
+- One-off helpers used once
+- Unnecessary abstraction layers (wrapper classes, indirection with no second use)
+- Verbose error strings that repeat the function name and obvious context
+- Defensive comments apologizing for the code
+
+## Reviewer output template
+
+```markdown
+# Code Smell Review
+
+**Verdict:** PASS | FAIL
+**Diff scope:** [command used, e.g. git diff HEAD]
+**Hunks reviewed:** N
+
+## Findings
+
+| # | Severity | Category | Location | Issue | Suggested fix |
+|---|----------|----------|----------|-------|---------------|
+| 1 | must_fix | comments | path:line | narrates obvious loop | delete comment |
+| 2 | must_fix | fallbacks | path:line | `or "default"` hides missing config | raise ValueError with key name |
+
+## Summary
+
+- must_fix: N
+- suggestion: N
+- false_positive: N (with justification)
+
+## Pass criteria
+
+PASS only when **must_fix = 0** for the current diff.
+```
+
+**Severity:**
+
+| Level | Meaning |
+|-------|---------|
+| `must_fix` | Blocks PASS — parent must fix and re-run |
+| `suggestion` | Does not block PASS; parent may fix or defer explicitly |
+| `false_positive` | Reviewer self-correction with justification |
+
+Default: comment noise, fallbacks, and assertiveness gaps are **`must_fix`**, not suggestions.
+
+## Subagent dispatch
+
+```
+Task(subagent_type: generalPurpose, readonly via prompt)
+
+Prompt:
+You are the smell reviewer. Read-only. Do not edit files.
+
+Input: the git diff below (hunks only). No conversation context.
+
+Apply the checklist in code-smell-review skill:
+- comment noise (what/change/section headers bad; why/docstrings ok)
+- naming, complexity, duplication, over-defensive code
+- assertive over fallbacks (no silent defaults for required things)
+- AI slop patterns
+
+Return the structured PASS/FAIL report. Be strict on must_fix items.
+Do not praise the code. Do not explain your process.
+
+<DIFF>
+...
+</DIFF>
+```
+
+Re-run after each fix pass with the fresh diff until PASS.
+
+## Anti-patterns
+
+- Parent skipping the gate because "the change is small"
+- Feeding the reviewer full files instead of diff hunks
+- Including conversation history in the reviewer prompt ( biases toward PASS)
+- Marking work done on FAIL with "user can fix later"
+- Replacing a fallback with an empty string instead of raising
+- Adding comments to explain bad names instead of renaming
+
+## Related skills
+
+- **[skill-orchestrator](../skill-orchestrator/SKILL.md)** — runs this skill in the correct pipeline order before close
+- **ce-simplify-code** — broader simplification (reuse, efficiency); run smell review first or after, not as a substitute
+- **ce-code-review** — full PR review with security/correctness personas; smell gate is a pre-merge hygiene check on agent-written diffs

agent_easy_framework-0.0.3/.cursor/skills/code-smell-review/examples.md

@@ -0,0 +1,162 @@
+# Code Smell Review — Examples
+
+Calibration examples for the smell reviewer. **Flag the bad; leave the good alone.**
+
+## Comments
+
+### Bad — narrates what
+
+```python
+# Get the user from the database
+user = db.get_user(user_id)
+
+# Return early if not found
+if user is None:
+    return None
+```
+
+**Fix:** Delete both comments. Names and structure are enough.
+
+### Bad — change narration
+
+```python
+# Added per review feedback — validate port range
+if not 1 <= port <= 65535:
+    raise ValueError(f"port out of range: {port}")
+```
+
+**Fix:** Delete the comment. The raise message is sufficient.
+
+### Bad — section header
+
+```python
+# --- HTTP transport setup ---
+
+def bind_http_server(host: str, port: int) -> None:
+    ...
+```
+
+**Fix:** Delete the header. Use a function name or module structure instead.
+
+### Good — non-obvious why
+
+```python
+# MCP streamable HTTP requires session id before tool calls (spec 2025-03).
+await client.initialize()
+```
+
+**Keep:** Documents an external constraint not visible from code alone.
+
+### Good — public docstring
+
+```python
+def add_tool(package: str, name: str, *, overwrite: bool = False) -> Path:
+    """Register a new tool module and wire it into the package registry."""
+```
+
+**Keep:** Public API surface; not inline noise.
+
+---
+
+## Assertive over fallbacks
+
+### Bad — silent default hides misconfiguration
+
+```python
+def load_profile(name: str) -> dict:
+    path = os.environ.get("AGENT_EASY_PROFILE") or "local"
+    ...
+```
+
+**Fix:** Require explicit config or raise:
+
+```python
+def load_profile(name: str) -> dict:
+    path = os.environ["AGENT_EASY_PROFILE"]  # or explicit arg with no env fallback
+    ...
+```
+
+### Bad — swallow and continue
+
+```python
+try:
+    registry.register(tool)
+except Exception:
+    pass  # tool might already exist
+```
+
+**Fix:** Catch the specific exception or check registration state; re-raise or raise a clear error.
+
+### OK — documented optional with explicit default
+
+```python
+def create_server(*, port: int = 8000) -> Server:
+    """Start HTTP MCP on ``port`` (default 8000 for local dev)."""
+```
+
+**Keep:** Default is part of the public contract, not a hidden fallback for missing config.
+
+---
+
+## Complexity & naming
+
+### Bad — name forces comment
+
+```python
+def process(data: list[dict]) -> list[dict]:
+    # Filter active items and map to ids
+    return [x["id"] for x in data if x.get("active")]
+```
+
+**Fix:** Rename and delete comment:
+
+```python
+def active_item_ids(items: list[dict]) -> list[str]:
+    return [item["id"] for item in items if item["active"]]
+```
+
+(Also flags defensive `.get("active")` if `active` is required — use direct access or validate upstream.)
+
+### Bad — deep nesting
+
+```python
+result = (
+    fetch_a()
+    if cond_a
+    else fetch_b()
+    if cond_b
+    else fetch_c()
+)
+```
+
+**Fix:** Early returns or if/elif chain with named intermediate values.
+
+---
+
+## AI slop
+
+### Bad — unnecessary helper
+
+```python
+def _normalize_name(name: str) -> str:
+    return name.strip().lower()
+
+def register(name: str) -> None:
+    register_impl(_normalize_name(name))
+```
+
+**Fix:** Inline if used once, or move to a shared util if the pattern repeats elsewhere.
+
+### Bad — verbose error
+
+```python
+raise ValueError(
+    "register_tool failed because the tool name parameter was invalid or empty"
+)
+```
+
+**Fix:**
+
+```python
+raise ValueError(f"tool name must be non-empty, got {name!r}")
+```