@topy-ai/maggie 0.7.61 → 0.8.1

package/bundled-tools/runtime/spirit_face.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""ONEMAN Core-Agent faces — the O mark IS the face.
+Thin accent rim (bigger face) -> larger, varied eyes. Mixed gender; women wear
+long hair. Distinct hair silhouette + one personality prop per agent."""
+import math
+from PIL import Image, ImageDraw
+W=H=28
+def _rgb(h):h=h.lstrip('#');return(int(h[0:2],16),int(h[2:4],16),int(h[4:6],16))
+def shade(c,a):
+    f=lambda v:max(0,min(255,round(v+(a/100)*((255-v)if a>0 else v))));return(f(c[0]),f(c[1]),f(c[2]))
+OUT=_rgb('14141e');WHT=_rgb('f7f7fb');EYE=_rgb('1b1b26')
+cx,cy=14,13;R_OUT=11.0;R_IN=8.6                      # thin rim -> big face
+SKINS={"light":_rgb('f0c49a'),"mid":_rgb('d89c70'),"tan":_rgb('c6895a'),"deep":_rgb('9c6a44')}
+def rect(px,x0,y0,x1,y1,c):
+    for y in range(max(0,y0),min(H,y1+1)):
+        for x in range(max(0,x0),min(W,x1+1)):px[(x,y)]=c
+def ytop(x):
+    dx=x-cx;return (cy-math.sqrt(R_OUT**2-dx*dx)) if abs(dx)<=R_OUT else None
+
+def draw_eyes(px,style,SK):
+    """Bigger eyes, varied. Left cols cx-5..-3, right cx+3..+5."""
+    def one(side,lash=False,shut=False,small=False,wide=False):
+        s=side
+        L=[cx+ s*3,cx+s*4,cx+s*5]
+        if shut:
+            for x in L:px[(x,cy-1)]=OUT
+            if lash:px[(cx+s*6,cy-2)]=OUT
+            return
+        for x in L:                                  # white block 3x2
+            px[(x,cy-2)]=WHT;px[(x,cy-1)]=WHT
+        pupx=cx+s*4
+        if wide:
+            px[(pupx,cy-1)]=EYE                      # small pupil, lots of white
+        elif small:
+            px[(pupx,cy-1)]=EYE
+        else:
+            px[(pupx,cy-1)]=EYE;px[(pupx,cy-2)]=EYE  # big pupil
+        px[(cx+s*3 if s<0 else cx+s*5,cy-2)]=WHT     # keep a white glint corner
+        if lash:
+            px[(cx+s*6,cy-2)]=OUT;px[(cx+s*5,cy-3)]=OUT;px[(cx+s*3,cy-2)]=OUT
+    if style=="wink":
+        one(-1);one(1,shut=True)
+    elif style=="lash":
+        one(-1,lash=True);one(1,lash=True)
+    elif style=="wide":
+        one(-1,wide=True);one(1,wide=True)
+    elif style=="small":
+        one(-1,small=True);one(1,small=True)
+    elif style=="happy":
+        for s in(-1,1): px[(cx+s*5,cy-1)]=OUT;px[(cx+s*4,cy-2)]=OUT;px[(cx+s*3,cy-1)]=OUT
+    else:  # round
+        one(-1);one(1)
+
+def hair_crown(px,HA,HAs,HAh,style):
+    def up(dx):
+        a=abs(dx)
+        return {"buzz":0,"short":1,"slick":1,"spiky":(3 if dx%2==0 else 1),
+                "longstraight":1,"longwavy":1,"ponytail":1,"longbob":1}.get(style,1)
+    def down(dx):
+        return {"buzz":1,"short":2,"slick":(3 if dx>0 else 1)}.get(style,2)
+    for x in range(cx-11,cx+12):
+        yt=ytop(x)
+        if yt is None:continue
+        base=round(yt)
+        if base>cy-2:continue
+        u=up(x-cx)
+        topy=base-u;boty=min(base+down(x-cx),cy-3)
+        for y in range(topy,boty+1):
+            if 0<=y<H:px[(x,y)]=HA
+        if 0<=topy<H:px[(x,topy)]=HAh
+        if 0<=boty<H and px.get((x,boty))==HA:px[(x,boty)]=HAs
+
+def hair_sides(px,HA,HAs,style):
+    # women's long hair: side panels of different length/shape
+    for x in range(cx-11,cx+12):
+        dx=x-cx;a=abs(dx)
+        if a<6 or a>10:continue
+        yt=ytop(x)
+        if yt is None:continue
+        top=round(yt)
+        if style=="longstraight":L=cy+7
+        elif style=="longwavy":L=cy+6+(1 if (x%2==0) else -1)
+        elif style=="longbob":L=cy+2
+        elif style=="ponytail":L=cy
+        else:L=cy-1
+        for y in range(top,min(H,L+1)):px[(x,y)]=HA
+        if L<H:px[(x,min(H-1,L))]=HAs
+    if style=="ponytail":
+        for yy in range(cy-4,cy+5):                  # tail on the right
+            for xx in range(cx+9,cx+12):
+                if abs((yy-cy))<=4-(xx-(cx+9)):px[(xx,yy)]=HA
+        px[(cx+9,cy+4)]=HAs
+        px[(cx+8,cy-5)]=HA                            # tie base
+
+def face(accent,hair,skin="mid",*,gender="m",hairstyle="short",eyes="round",
+         mouth="smile",prop=None,propcol="#caa472",hoodie=False,band=None,mask=None,specs=False):
+    AC=_rgb(accent);ACd=shade(AC,-30);SK=SKINS[skin];SKs=shade(SK,-20)
+    HA=_rgb(hair);HAs=shade(HA,-28);HAh=shade(HA,22)
+    px={}
+    for y in range(H):
+        for x in range(W):
+            d=math.hypot(x-cx,y-cy)
+            if d<=R_OUT:px[(x,y)]=(AC if d<R_OUT-0.9 else ACd) if d>=R_IN else SK
+    for y in range(0,cy-3):
+        for x in range(cx-2,cx+3):
+            if px.get((x,y)) in(AC,ACd):del px[(x,y)]
+    for x in range(cx-5,cx+6):
+        if px.get((x,cy+5))==SK:px[(x,cy+5)]=SKs
+    if gender=="f":hair_sides(px,HA,HAs,hairstyle)    # draw long hair behind/around first
+    if hairstyle!="bald":hair_crown(px,HA,HAs,HAh,hairstyle)
+    draw_eyes(px,eyes,SK)
+    px[(cx,cy+2)]=SKs                                 # nose
+    if mouth=="smile":
+        px[(cx-2,cy+4)]=OUT;px[(cx-1,cy+5)]=OUT;px[(cx,cy+5)]=OUT;px[(cx+1,cy+5)]=OUT;px[(cx+2,cy+4)]=OUT
+    elif mouth=="flat":rect(px,cx-2,cy+4,cx+1,cy+4,OUT)
+    elif mouth=="smirk":
+        px[(cx-1,cy+5)]=OUT;px[(cx,cy+5)]=OUT;px[(cx+1,cy+4)]=OUT;px[(cx+2,cy+3)]=OUT
+    elif mouth=="open":rect(px,cx-2,cy+4,cx+1,cy+5,OUT);px[(cx-1,cy+5)]=_rgb('7a1a12')
+    elif mouth=="lips":rect(px,cx-2,cy+4,cx+1,cy+4,_rgb('c0392b'))   # lipstick
+    # props
+    if prop=="cigar":
+        PC=_rgb(propcol);rect(px,cx+2,cy+4,cx+8,cy+4,PC);px[(cx+2,cy+4)]=shade(PC,-25)
+        px[(cx+8,cy+4)]=_rgb('ff4422');px[(cx+9,cy+4)]=_rgb('ffb08a')
+        px[(cx+9,cy+2)]=_rgb('8a8a9a');px[(cx+10,cy+1)]=_rgb('6a6a7a')
+    elif prop=="shades":
+        rect(px,cx-6,cy-2,cx-2,cy,OUT);rect(px,cx+2,cy-2,cx+6,cy,OUT)
+        rect(px,cx-1,cy-2,cx+1,cy-2,OUT);px[(cx-7,cy-2)]=OUT;px[(cx+7,cy-2)]=OUT
+        px[(cx-5,cy-1)]=_rgb('3a3a4a');px[(cx+3,cy-1)]=_rgb('3a3a4a')
+    elif prop=="glasses":
+        for x in range(cx-6,cx-1):px[(x,cy-2)]=OUT;px[(x,cy)]=OUT
+        px[(cx-6,cy-1)]=OUT;px[(cx-2,cy-1)]=OUT
+        for x in range(cx+2,cx+7):px[(x,cy-2)]=OUT;px[(x,cy)]=OUT
+        px[(cx+1,cy-1)]=OUT;px[(cx+6,cy-1)]=OUT;px[(cx,cy-1)]=OUT
+    elif prop=="monocle":
+        for x in range(cx+2,cx+7):px[(x,cy-2)]=OUT;px[(x,cy)]=OUT
+        px[(cx+1,cy-1)]=OUT;px[(cx+6,cy-1)]=OUT
+        px[(cx+4,cy+1)]=_rgb('d4af37');px[(cx+4,cy+2)]=_rgb('d4af37')
+    elif prop=="pen":
+        PC=_rgb(propcol)
+        for i in range(5):
+            x=cx+8+i;y=cy-2-i
+            if 0<=x<W and 0<=y<H:px[(x,y)]=PC
+        px[(cx+8,cy-2)]=_rgb('2a2a34');px[(cx+12,cy-6)]=shade(PC,30)
+    elif prop=="headset":
+        rect(px,cx-12,cy-6,cx-12,cy+1,OUT);px[(cx-12,cy+2)]=OUT
+        rect(px,cx-13,cy+1,cx-12,cy+3,EYE);rect(px,cx-12,cy+3,cx-6,cy+4,OUT);px[(cx-6,cy+4)]=_rgb('ff4422')
+    elif prop=="earbuds":
+        px[(cx-9,cy)]=WHT;px[(cx-9,cy+1)]=WHT;px[(cx+9,cy)]=WHT;px[(cx+9,cy+1)]=WHT
+    elif prop=="bandana":
+        BC=_rgb(propcol)
+        for x in range(cx-11,cx+12):
+            yt=ytop(x)
+            if yt is None:continue
+            base=round(yt)
+            for y in range(base-1,base+3):
+                if 0<=y<H and y<=cy-3 and px.get((x,y)) not in(None,SK,SKs):px[(x,y)]=BC
+        px[(cx-10,cy-2)]=BC;px[(cx-11,cy-1)]=BC;px[(cx-11,cy)]=shade(BC,-22)
+        for x in range(cx-6,cx+7,3):px[(x,cy-5)]=shade(BC,-22)
+    # ---- combinable wearables (Founder) ----
+    if hoodie:
+        HC=_rgb('161b22')
+        for y in range(cy-2,H):
+            for x in range(W):
+                d=math.hypot(x-cx,y-cy)
+                if R_OUT<d<=R_OUT+2.4 and px.get((x,y)) is None: px[(x,y)]=HC
+    if band:
+        BC=_rgb(band); BCd=shade(BC,-24)
+        for y in range(0,cy-6):                              # hair crown above the (raised) band
+            for x in range(cx-9,cx+10):
+                if px.get((x,y))==SK: px[(x,y)]=HA
+        for y in (cy-6,cy-5,cy-4):                           # headband, raised a touch
+            for x in range(cx-10,cx+11):
+                yt=ytop(x)
+                if yt is None: continue
+                if y>=round(yt)-1 and px.get((x,y)) is not None: px[(x,y)]=BC
+        for strand in (0,1):                                 # two tails, both streaming up-right (wind-blown)
+            for k in range(6):
+                xx=cx+8+k; yy=(cy-2-strand*2)-(k*2)//3
+                if 0<=xx<W and 0<=yy<H: px[(xx,yy)]=BC if k<3 else BCd
+    if mask:
+        MC=_rgb(mask);MCs=shade(MC,34);GL=_rgb('39d353')
+        for y in range(cy+1,cy+10):                         # dark mask over nose+mouth+chin (follows the face)
+            for x in range(cx-8,cx+9):
+                if px.get((x,y)) in(SK,SKs): px[(x,y)]=MC
+        for x in range(cx-5,cx+6):
+            if px.get((x,cy+1))==MC: px[(x,cy+1)]=MCs        # ridge over the nose
+        for y in range(cy+2,cy+8):
+            if px.get((cx,y))==MC: px[(cx,y)]=MCs            # centre seam
+        for k in range(3): px[(cx+3,cy+4+k)]=GL;px[(cx+4,cy+4+k)]=GL   # green vent stripes
+    if specs:
+        LENS=_rgb('1f8a3a')
+        rect(px,cx-6,cy-2,cx-2,cy,OUT); rect(px,cx-5,cy-2,cx-3,cy-1,LENS); px[(cx-4,cy-1)]=_rgb('0c1a10')
+        rect(px,cx+2,cy-2,cx+6,cy,OUT); rect(px,cx+3,cy-2,cx+5,cy-1,LENS); px[(cx+4,cy-1)]=_rgb('0c1a10')
+        px[(cx-1,cy-1)]=OUT;px[(cx,cy-1)]=OUT;px[(cx+1,cy-1)]=OUT      # bridge
+    return px
+
+FOUNDER=("FOUNDER","#2fbf52","m",dict(hair="#141419",skin="light",hairstyle="short",eyes="happy",mouth="flat",band="#e23b3b",mask="#12201a",hoodie=True,specs=True))
+
+def render(px,scale,bg=None):
+    img=Image.new("RGBA",(W*scale,H*scale),(bg or(0,0,0,0)));d=ImageDraw.Draw(img)
+    for (x,y),c in px.items():
+        if c is not None:d.rectangle([x*scale,y*scale,(x+1)*scale-1,(y+1)*scale-1],fill=c+(255,))
+    return img
+
+CAST=[
+ ("CEO","#f59e0b","m",dict(hair="#2a2018",skin="mid",  hairstyle="slick",eyes="round",mouth="smirk",prop="cigar")),
+ ("CPO","#8b5cf6","f",dict(hair="#3a2418",skin="tan",  hairstyle="longwavy",eyes="lash",mouth="smile",prop="pen",propcol="#f2c75a")),
+ ("CMO","#ec4899","f",dict(hair="#4a2a18",skin="light",hairstyle="longstraight",eyes="lash",mouth="lips",prop="shades")),
+ ("CRO","#84cc16","m",dict(hair="#1c1c22",skin="mid",  hairstyle="spiky",eyes="wide",mouth="open",prop="headset")),
+ ("CTO","#3b82f6","m",dict(hair="#1c1c22",skin="tan",  hairstyle="buzz",eyes="round",mouth="flat",prop="glasses")),
+ ("COO","#06b6d4","f",dict(hair="#15151c",skin="deep", hairstyle="ponytail",eyes="lash",mouth="smile",prop="earbuds")),
+ ("CFO","#2dd4bf","f",dict(hair="#6a4a2a",skin="light",hairstyle="longbob",eyes="lash",mouth="flat",prop="monocle")),
+ ("CSO","#6366f1","m",dict(hair="#1c1c22",skin="mid",  hairstyle="short",eyes="wide",mouth="flat",prop="bandana",propcol="#ef4444")),
+]
+if __name__=="__main__":
+    scale=10;gap=14;lblh=22;cols=4;rows=2;cw=W*scale;ch=H*scale
+    sheet=Image.new("RGBA",(cols*cw+(cols+1)*gap, rows*(ch+lblh)+gap),(13,13,20,255));d=ImageDraw.Draw(sheet)
+    for i,(nm,acc,g,p) in enumerate(CAST):
+        im=render(face(acc,gender=g,**p),scale)
+        x=gap+(i%cols)*(cw+gap);y=lblh+(i//cols)*(ch+lblh)
+        sheet.paste(im,(x,y),im);d.text((x+4,y-16),f"{nm} {'F' if g=='f' else 'M'} {p['hairstyle']}/{p['prop']}",fill=(220,220,235))
+    sheet.save("/tmp/face_preview.png");print("wrote",sheet.size)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.61",
+  "version": "0.8.1",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/agent-goal-design.md

@@ -0,0 +1,92 @@
+# Goal-led AI agent design
+
+A reusable method for defining the agents in a multi-agent product so a single
+human can run a company by stating intent, not by operating tools. Distilled
+from the ONEMAN.APP cofounder build; pairs with the `maggie-spirit` skill (give
+each designed agent a spirit/avatar) and `maggie-assistant-tools` (expose an
+agent's capabilities safely).
+
+## Principle
+
+The human sets a **goal**; the agents turn it into work and keep the human in
+the loop only for judgement and approval. Each agent owns one lane, declares the
+**capability classes** it may use, and runs under a **risk ceiling** with
+explicit approval gates. Nothing that is risky, public, or spends money happens
+without a human yes.
+
+## Define each agent with a role contract
+
+One `role.yaml` per agent. Recommended fields:
+
+```yaml
+role: CTO                     # the lane
+name: AI CTO                  # display name
+persona: Turing               # inspiration, not impersonation
+spirit: Engineering           # one-word identity (drives the spirit accent/motif)
+summary: >                    # what it owns, in one or two sentences
+  Technical design, build, integrate, test and deploy. Production deployment is
+  gated behind human approval.
+responsibilities: [design, build, integrate, test, deploy, observe]
+constraints: [no prod deploy without approval, no secrets in source]
+allowed_capability_classes: [app.scaffold, app.build, app.test, code.review,
+  deploy.release, integration.connect, ops.observe, job.execute]
+default_risk_ceiling: L1      # L0 read -> L3 irreversible/public/paid
+business_system: Execution    # which paired system (e.g. with COO)
+raci: { new_service_app: "A", security_verdict: I }
+interfaces: { mcp: planned, cli: planned, api: planned }
+```
+
+- **Capability classes**, not freeform skills, are the unit of authority. They
+  are stable `area.verb` identifiers (`content.publish`, `revenue.close`,
+  `security.scan`) that a UI can list and a gate can check. These are the
+  "skills" a product surfaces per agent.
+- **One CEO orchestrates.** The CEO owns `goal.decompose`, `mission.manage`,
+  `plan.compose`, `priority.rank`, `outcome.accept`: it turns intent into
+  missions with acceptance criteria, delegates each to the right agent, and
+  signs off - it never bypasses security or budget approval.
+- **Security holds a non-overridable veto.** A high-risk security verdict cannot
+  be overruled by another agent.
+- **Finance is explain-only.** Financial facts come from deterministic data
+  (billing/usage ledger, Stripe); the CFO reconciles and advises, it is not the
+  source of truth.
+
+## Risk ceilings and approval gates
+
+| Level | Meaning | Gate |
+|---|---|---|
+| L0 | read-only | none |
+| L1 | internal writes (drafts, plans, workflows) | logged |
+| L2 | customer-facing or public (publish, close a deal) | human approval |
+| L3 | irreversible / paid / production (deploy, transfer) | human approval + audit |
+
+Every agent declares a `default_risk_ceiling`; an action above it stops for an
+explicit human yes. Log every action; make L2/L3 produce an approval card.
+
+## The goal loop
+
+1. The human states what the business should do.
+2. The CEO writes missions with acceptance criteria.
+3. Each mission is delegated to the agent whose lane and capability classes fit.
+4. Agents work their lane; risky/public/paid steps wait for approval.
+5. The CEO reviews outcomes against the acceptance criteria and signs off, or
+   sends the mission back.
+6. The human stays the only human in the loop - approve, steer, ship.
+
+## Surfacing agents to users
+
+Each agent reads cleanly as a profile: persona name, spirit, its capability
+classes (its "skills"), and the service apps it manages. Give it a spirit/avatar
+with `maggie-spirit` (shared 32-state motion vocabulary, per-agent accent) so
+status (idle, working, deploying, success, blocked, secure) reads the same
+across the whole team. Mark an agent "shipped" only when its product is actually
+live.
+
+## Checklist
+
+- [ ] One lane per agent; no two agents own the same decision.
+- [ ] Capability classes are `area.verb`, stable, and enumerable.
+- [ ] A single orchestrator (CEO) owns decomposition and sign-off.
+- [ ] Security veto and finance-is-explain-only are encoded, not assumed.
+- [ ] Every agent has a risk ceiling; L2/L3 actions gate on human approval.
+- [ ] Persona is inspiration, not impersonation of a real person.
+- [ ] Each agent has a spirit/avatar from the shared 32-state base set.