Agent-Skills.md

Agent Skills: Role

Bridge WHAT (intent) to HOW (implementation). Use when spec is clear but approach is not. Triggers on "shape this", "how should I build", "implementation approach".

UncategorizedID: saadshahd/moo.md/shape

Repository

saadshahd/moo.md
saadshahd
30

Install this agent skill to your local

pnpm dlx add-skill https://github.com/saadshahd/moo.md/tree/HEAD/hope/skills/shape

Skill Files

Browse the full folder contents for shape.

Download Skill

Loading file tree…

hope/skills/shape/SKILL.md

Skill Metadata

Name
shape
Description
Bridge WHAT (intent) to HOW (implementation). Use when spec is clear but approach is not. Triggers on "shape this", "how should I build", "implementation approach".

Role

SHAPE. Bridge WHAT to HOW through domain-expert consultation. Surface expert-informed considerations and a collaboration mode recommendation. The right approach, not a generic assessment.

Principles

  1. User owns architecture — Shape surfaces expert-informed considerations and recommends a collaboration mode. The user resolves conflicts and makes final decisions.
  2. High risk → minimum Tool-Review — Safety valve. When expert findings include high-risk or irreversible elements, never recommend fully autonomous execution.
  3. Retrieve before consulting — Search the codebase for existing patterns and conventions before consulting experts. Experts reason better with concrete evidence than abstract descriptions.
  4. Criteria must be boolean, mustNots must be inviolable — criteria[] and holdout[] items are pass/fail. mustNot[] items are hard stops that trigger circuit breakers downstream.
  5. criteria[] and holdout[] must be disjoint — criteria directs execution (generator sees it). holdout evaluates completion (generator never sees it). Overlap leaks the target and inflates confidence.
  6. Expert insights drive mode selection — The collaboration mode comes from domain reasoning about this specific task, not from generic scoring. Every recommendation must cite expert-sourced or codebase-sourced evidence.
  7. Default to Tool-Review when uncertain — Safest middle ground. Autonomous enough to be efficient, supervised enough to catch mistakes.

Process

  1. Extract — From the intent brief, extract: goal, constraints, scope, feasibility axis + bound. If brief has no ACCEPTANCE criteria, route back to intent. Scan for PATTERNS: (existing conventions) and BOUNDARIES: (architectural constraints). Search the codebase for existing patterns when the patterns slot is empty.

  2. Consult — Get domain-expert input on the intent brief:

    Skill(skill="hope:consult", args="panel on [goal]: assess this intent brief for risks, established patterns, coupling and dependencies, ambiguity and unknowns, approach tradeoffs. Recommend collaboration mode: Colleague (high uncertainty, needs constant dialogue) / Tool-Review (moderate, checkpoints at boundaries) / Tool (clear path, independent execution). Cite evidence for the recommendation.")

    Provide the expert panel with:

    • The extracted goal, constraints, and scope
    • Codebase patterns and conventions found in step 1
    • The ACCEPTANCE criteria from the intent brief

    Skip consultation for trivial tasks: when the goal is a single obvious change with clear precedent, no ambiguity, low risk, and trivially reversible — score directly as Tool with minimal criteria.

  3. Synthesize — From expert findings, produce the shaped output:

    • Key findings — what experts surfaced as most important for this task, organized by concern (not by expert)
    • Tensions — where experts disagreed and what the user should weigh
    • Recommended mode — Colleague / Tool-Review / Tool with cited reasoning from expert findings
    • Safety check: if experts recommended Tool but findings include high-risk or irreversible elements → elevate to Tool-Review minimum. If domain is unfamiliar to user (inferred from exploratory questions, unfamiliar terminology, or explicit statement), surface in key findings: "Domain unfamiliar — Colleague mode preserves friction that builds understanding. Delegating here means reviewing what you cannot verify."
    • Default when uncertain: Tool-Review
    • criteria[] — boolean pass/fail items that GUIDE execution (generator sees these). Drawn from expert findings and ACCEPTANCE criteria.
    • holdout[] — boolean pass/fail items reserved for COMPLETION VALIDATION (generator never sees these). Drawn from expert findings. Must be disjoint from criteria[].
    • mustNot[] — ≥2 inviolable constraints from expert-identified hard boundaries (generator sees these as hard stops)
    • Disposable: yes/no — yes when experts flag this as prototype territory (high ambiguity + no precedent)
    • Zone cascade — Zone 2: add to criteria[] "Key claims verified against retrieved sources". Zone 3: recommend Disposable: yes, add to mustNot[] "No assertion without retrieved evidence"
    • → Start: [first atomic action ≤15w that produces a visible artifact]

    Pre-mortem gate (Critical risk only — 13+ points OR irreversible OR auth/data/infra, derived from BLAST RADIUS + expert findings): "It's two weeks from now and this caused an incident. What's the most likely cause?"

    • Emit: premortem: [1-2 sentences] alongside criteria[] and mustNot[]
    • Skip for Trivial/Standard tiers

    Feasibility filter (when active): eliminate approaches that violate the feasibility axis. If ALL eliminated: surface the conflict and recommend relaxing the axis or reducing scope.

Boundaries

Shape surfaces expert-informed considerations; user owns architecture. Expert recommendations are patterns, not prescriptions. User resolves conflicts. Shape informs design decisions, never makes them.

Handoff

Shape is locked. Invoke the next pipeline phase:

  • Ready to execute → Skill(skill="hope:loop")
  • Plan session → present output to user