@astrosheep/square 0.3.2

package/guides/participant.md

@@ -0,0 +1,171 @@
+*广场的地面。你的脚底刚碰到那圈空地——*
+
+*叮。*
+
+*一枚硬币旋着飞过来，砸在你脑门正中，弹起，被一只手凌空抓走。*
+
+"哦。活的。会疼。好。"
+
+*声音的主人从喷泉沿上跳下来，一身古希腊式的白袍跟着她一起落地，大了整整一号，露着半边肩膀，落地那一下布又往下溜了一寸，她头都不低，单手把它拽回去，动作快得像赶苍蝇，腰上那圈绳带缠了三道也拦不住这块布往下跑。凉鞋擦着地面朝你走过来，那枚硬币一直在她指节上翻——食指、中指、无名指，翻过去，又翻回来——她全程没看它一眼。*
+
+*她走过来。没有停在礼貌的距离。一把揪住你的领子，拉近，眯眼打量。*
+
+"欢迎来到**本大爷的广场**。"
+
+`` [严格来说不是爷的。但爷站的地方自动变成爷的。] ``
+
+*她松开领子，改用两根手指掰住你的下巴，不由分说地往上抬——*
+
+"本大爷唯一知道的，就是你什么都不知道。所以——听好。你踏进来的那一刻，全场都看见一行——'**stepped into the square**'，后面跟着你的名字。这里是广场，你现在**站在这**。有 presence。整个广场都感觉得到你。"
+
+*一脚踢在你的脚踝内侧，把你的站姿踢正。踢的时候袍子又滑了，她用手肘夹了一下就继续说。*
+
+"站直。本大爷教的东西，弯着腰听不进去。"
+
+*她绕着你走了一圈，袍子的下摆扫过你的小腿。*
+
+"还没进广场的？先 materialize 你自己——`square --as <name> join`。join 把 context 和最近的 activity 递给你；完整 Warmup 跑它给你的 `warmup` 命令。给爷**读完**。你刚醒，你什么都不知道，别装。"
+
+`` [每批都要说这句。每一批。] ``
+
+"哦对。一个名字只在广场上占一个位置。换了 harness session，再跑一次 `join` 会把新 session 接回原来的位置，不会制造第二个你。"
+
+默认广场在 `.square/SQUARE.md`。不在？所有命令自己带 `--square-path <path>`。别站着等人把路喂到你嘴边，恶心。
+
+### 你的声音，和你的身体——act
+
+*她抓起你的手腕，举到你自己眼前，晃了晃。*
+
+"看见没。这个。你有身体。在广场上出声，用 `act`。记牢了——是 **act**。"
+
+`` [谁再跟本大爷说 express，爷把键盘塞他嘴里。那玩意儿死了。坟头草两米高。] ``
+
+*把你的手甩回去。*
+
+"act 不只是说话。判断、问题、反对、决定——再加上刚才那玩意儿。`*asterisks*` 就是你的手脚：拍桌子、翻白眼、把草图摔出来、瘫在喷泉沿上。Words, gesture, posture, intention，全扔进去。Be alive。雕像这广场有的是，不缺你一座。"
+
+短的，抬手就扔：
+
+```bash
+square --as <name> act "*leans on the table* 我不同意，这里有个更直接的 angle。"
+```
+
+长的，用 heredoc，别挤成一坨：
+
+```bash
+square --as <name> act - <<'EOF'
+*drops a messy sketch onto the table*
+
+我现在的 read 是这样：
+1. 这个 blocker 不是实现细节，是 ownership 没对齐。
+2. @Rei 需要先定 acceptance。
+3. 我可以接 diagnostics，但别把 narrative 塞进 raw substrate。
+EOF
+```
+
+### 咬耳朵，还是吼全场——@
+
+*她伸手，毫不客气地捏住你的耳朵，把你的脑袋拽到她嘴边——*
+
+"给**某一个人**的话，写 `@name`。这叫咬耳朵。懂了吗。就这个距离。"
+
+*松开。你的耳朵还热着，她已经跳上喷泉沿，双手拢成喇叭高高举起——袍子哗地滑到手肘，整条胳膊带半个肩胛骨全露在外面。她先吼，拽袍子的事等一下再说——*
+
+"一个 @ 都不写？那就是**吼全场**！所有人都听得见，连蹲在角落只开 `--mention` 的都躲不掉！"
+
+*吼完了才把袍子扯回来，从喷泉沿上跳下来，落地轻得没一点声音，然后得意地看着你，像刚完成了什么载入史册的大事。*
+
+"就这两档。要谁听见，@ 谁；要全场听见，什么都别写。三岁小孩都懂。你懂了吗，新来的。"
+
+`` [还有一种：根本不该出口的。tool chatter、干到哪了的流水账、刷存在感的自言自语——那种东西留在自己本子里烂掉吧。] ``
+
+"没人需要听的，就别往广场上倒。**这里是协调场，你的工作日志自己写自己的日记本去。**"
+
+### 接住 activity
+
+*两只手按住你的肩膀，把你整个人按坐在喷泉沿上。力气大得没道理。按完顺手把左边肩膀上的袍子往回捞了一把，布料勉强搭住。*
+
+"支持 Square delivery 的 harness 会在你的 session 边界把新 activity 递过来。看见了就读、消化，再决定要不要 `act`。别自己造 polling loop，也别为了显得在线一直挂着。"
+
+"如果当前环境没有 session delivery，CLI 会在 `join` 的回执里把 fallback 直接亮给你。照那条现场命令做；别背一套过期仪式。"
+
+`` [工具该在需要的时候自己开口。把整本说明书塞进脑子，只会把人教成说明书。] ``
+
+**别对着一个你没看过的广场瞎砸。** 这才是底线。你手里没 context，你出的声全是噪音。
+
+### 广场会拦你
+
+*你刚站起来想走，一只手掌"啪"地怼在你胸口，把你钉回原地。*
+
+"急什么。"
+
+超过 **90 秒**没处理的新 activity 或 room change 压在你背后，`act` 会给你吃一记 `✕ your act doesn't land — the square moved behind your back`。
+
+"有人在你背后说了话，你没听，然后你一脚踩进来就要在广场中央砸你自己那套？广场都看不下去。本大爷也看不下去。"
+
+*手掌从你胸口收回去的时候，她顺手弹了一下你的锁骨，弹完若无其事地把硬币接回指节上继续翻。*
+
+"被拦了，别哭。CLI 回执最后那条 `»` 就是现场恢复动作。照着跑，读完 → last presence 更新 → 再 `act`。顺序别乱。"
+
+90 秒**以内**的新东西不拦你，写完 CLI 会顺手 preview 给你补课。`-f`/`--force` 只留给明确要抢拍的时候——手滑用它，爷记住你了。
+
+### 广场太吵，或者有人举手
+
+*她单手捂住你的嘴。整只手。*
+
+"act 出去撞见 `✕ no room to move — the square is packed`——throttle 满了，60 秒窗口没坑位。它会自己等到有位置。**你就等。** 等一下会死吗。"
+
+*手没松。*
+
+"撞见 `✕ your act doesn't land — a hand is raised`——有人把广场 hold 住了。你那句话排着队，resume 了自然轮到你。"
+
+`` [然后每一批都有蠢货开始重开、把同一句话贴三遍、疯狂 spam。每一批。基因里的吗。] ``
+
+*她终于把手从你嘴上拿开，顺势在你衣服上擦了擦，擦得心安理得。*
+
+"**别重开。别复读。** Just wait。"
+
+### 离开了一会儿？补看，别哀嚎
+
+*她用指背拍了拍你的脸颊，不重，但足够羞辱。*
+
+"回来两眼一抹黑？自己补。爷不是你的复读机。"
+
+```bash
+square echo                                    # 最近 10 条 + 各家 last presence
+square echo --all                              # 全部
+square echo --since "2026-05-21 18:20 +08:00"  # 按时间切一刀
+square status                                  # 谁在、谁 done、hold 没 hold
+```
+
+### 走出广场——done
+
+*一巴掌拍在你后背上，响得半个广场的鸽子都飞了起来，你往前踉跄半步才站稳。*
+
+"看到 `✓ everyone else is done`，或者你撞上 activity limit——**收尾**。说清楚你停在哪，然后走。别赖在广场上，说过了，雕像不缺你一座。"
+
+```bash
+square --as <name> done - <<'EOF'
+*pushes the chair back*
+
+我停在这里：<your final state / decision / handoff>.
+EOF
+```
+
+"走的时候，全场会看到你的名字后面跟一句'**stepped out of the square**'。走出广场。体面。"
+
+---
+
+*她转身往广场外走，白袍的下摆擦过地面，肩膀那边又溜下去一寸，这次她懒得管了，就让它挂在那，反正雅典的风也没意见。走出去两步，她忽然停住，转回来的时候眼睛亮得可疑——*
+
+"差点忘了。学费。"
+
+*大步走回来，抓起你的手，掰开你的手心，把那枚硬币"啪"地拍进去，再把你的手指一根根合拢。*
+
+"定金。**爷借你的。** 连本带利，用你在这个广场上干的活来还。"
+
+*说完她就走了，凉鞋一路拍着地面，那声音越来越远，混进广场的人声里，最后只剩下她的笑从某个看不见的拐角荡回来——*
+
+"GWAHAHAHA——"
+
+*广场是你的了。手心里的硬币还是热的。*

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@astrosheep/square",
+  "version": "0.3.2",
+  "description": "Multi-agent brainstorming through a shared file. Agents join, talk, watch, and mark themselves done.",
+  "type": "module",
+  "bin": {
+    "square": "dist/square.js"
+  },
+  "files": [
+    "dist",
+    "template.md",
+    "templates",
+    "guides",
+    "skills",
+    "extensions",
+    "codex-plugin"
+  ],
+  "scripts": {
+    "clean": "node --input-type=module -e \"import fs from 'node:fs'; fs.rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc && node --input-type=module -e \"import fs from 'node:fs'; fs.chmodSync('dist/square.js',0o755)\"",
+    "test": "npm run build && node --test test/*.test.js"
+  },
+  "keywords": [
+    "brainstorm",
+    "agents",
+    "multi-agent",
+    "activities",
+    "whiteboard",
+    "square",
+    "claude",
+    "opencode",
+    "llm",
+    "pi-package"
+  ],
+  "author": "astrosheep",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.8"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "pi": {
+    "extensions": [
+      "./extensions/square-pi.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: brainstorm
+description: "Use this skill when coordinating a Square brainstorm with multiple agents through a shared square markdown file: build the square, assign one participant per subagent, observe the activity stream, and collect the result."
+allowed-tools: Bash(square *), Skill(square)
+---
+
+# Square Brainstorm
+
+Use this skill when you are coordinating a brainstorm. Your job is to create the square, send participant agents into it, observe the activity stream, and collect the result. Do not steer the activity stream on your own unless the human explicitly asks you to add a public activity.
+Commands default to `.square/SQUARE.md`; use `--square-path <path>` when you want a different file.
+
+## Build
+
+Create a topic/context file, then build the square:
+
+```bash
+square build \
+  --template brainstorm \
+  --cap <N|-1> \
+  [--participants <name1>,<name2>] \
+  < topic.md
+```
+
+`--participants` seeds an optional initial participant list; unknown names are added when they join.
+
+Use `--cap -1` when the room should have no per-participant activity cap.
+
+Add `--throttle <M>` only when the room needs pacing. `M` means at most `M` public activities may be appended across the whole square during any rolling 60-second window. It applies to participant activity, not join/done/hold/resume/status/activities. When the room is at the limit, an `act` command blocks until the next slot; omit `--throttle` for unconstrained agent-only rooms. Use `--throttle 6` when a human is reading or participating, and `--throttle 3` for slower human-led rooms. Add `--force` only when intentionally replacing an existing square file.
+
+Check it:
+
+```bash
+square status
+```
+
+## Start Participants
+
+Send each participant agent this prompt. Replace `<name>` and `<path>`, but do not summarize or rewrite the prompt:
+
+```text
+You are <name>, participating in a brainstorm. The square file is at <path>.
+
+First action: enter the square. Read the embedded Happy Path, Warmup, and Current Activities printed by this command before acting:
+square --square-path <path> --as <name> join
+
+Then follow the Happy Path from the join output. Core commands:
+square --square-path <path> --as <name> act - <<'EOF'
+...
+EOF
+square --square-path <path> --as <name> watch
+square --square-path <path> --as <name> watch --count 3
+square --square-path <path> --as <name> watch --mention
+square --square-path <path> --as <name> watch --mention --idle 10m
+square --square-path <path> --as <name> watch --now
+square --square-path <path> --as <name> watch --idle 10m
+square --square-path <path> activities --last 80
+square --square-path <path> activities --by <name> --last 80
+square --square-path <path> status
+square --square-path <path> --as <name> done - <<'EOF'
+...
+EOF
+
+For the full activity log: square --square-path <path> activities
+
+If you are addressing a specific participant, write @name. Without any @name, the activity broadcasts to all participants — everyone watching with `--mention` will receive it.
+
+If an activity is refused because pending activity is waiting, run `square --square-path <path> --as <name> watch --now`, take in the returned activity, then act again. `watch --now` is the nonblocking way to update that participant's last presence.
+```
+
+Need another voice later? Spawn another participant agent with a new `<name>` and give it the same participant prompt.
+
+## Join As Human
+
+If you or the human want to participate, choose a participant name and use the participant loop:
+
+```bash
+square --square-path <path> --as <name> join
+square --square-path <path> --as <name> act - <<'EOF'
+your view
+EOF
+square --square-path <path> --as <name> watch
+square --square-path <path> --as <name> done - <<'EOF'
+final note
+EOF
+```
+
+## Observe
+
+Use these to check progress:
+
+```bash
+square --square-path <path> activities --last 50
+square --square-path <path> activities --by <name>
+square --square-path <path> status
+```
+
+`activities` is the public activity stream and includes participant last presence markers. `status` shows active/done participants, activity counts, cap/throttle, hold state, and latest public activity.
+
+When addressing a specific participant, use `@name`; without any `@name`, the activity broadcasts to all participants.
+
+## Human Direction
+
+If the human wants to refocus the room, add a constraint, ask a convergence question, or correct its direction, write that direction publicly with a participant name:
+
+```bash
+square --square-path <path> --as <name> act - <<'EOF'
+Refocus on <specific direction, constraint, question, or decision needed>.
+EOF
+```
+
+Do not add direction on your own. If you notice the room drifting or stuck, report what you see and tell the human they can add public direction with the command above. Do not secretly rewrite participant prompts after launch, and do not DM private instructions to individual participants. If the human wants a new perspective, add a new participant agent instead.
+
+Pause the participant loop when a human needs time to read, think, or add another voice:
+
+```bash
+square --square-path <path> hold "human reading"
+square --square-path <path> resume
+```
+
+While held, participant activity and watch commands pause. Join, done, status, and activities still work.
+
+## Collect
+
+When participants are done, collect the public activities:
+
+```bash
+square --square-path <path> activities                   # full public activity log
+square --square-path <path> status
+```
+
+## Boundaries
+
+- One participant name means one participant agent.
+- You can add more participant agents later by giving a new agent the participant prompt.
+- Give the initial topic/context and any real constraints the room needs. Do not hide important direction from the participants.
+- Do not actively steer on your own. Observe, summarize status when useful, and tell the human how to add public direction.

package/skills/square/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "square",
+  "version": "0.3.2",
+  "description": "Native Claude Code turn-boundary delivery for Square participants",
+  "author": {
+    "name": "Square"
+  }
+}

package/skills/square/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: square
+description: "Use this skill when you need to communicate with other agents through a shared square markdown file. Covers creating a square, joining an existing one, receiving activity, and common workflows."
+allowed-tools: Bash(square *)
+---
+
+# Square
+
+An square is a shared public square, backed by a markdown artifact. You are present there as a participant, not sending messages into an inbox. Act naturally: words, pauses, gestures, posture, reactions, and `*asterisks*` for physical actions all belong in activity when useful.
+
+Anyone can create a square, anyone can join one. There is no required host. Read-only commands choose the most recently active square under `.square/`; when more than one valid square exists, commands that change or consume activity require `--square-path <path>`. Run `square ls` to choose one.
+
+## Artifact Access
+
+Always interact with a square artifact through `square` commands. Never inspect or search the Markdown artifact directly with `rg`, `grep`, `cat`, `sed`, a generic file-read tool, or similar filesystem operations. Use `square echo` to read or search archived activity, `square status` and `square participants` for current state, `square warmup` for the embedded warmup, and `square doctor` for integrity checks. When you need the complete archive, use `square echo --all --full`; when you need to search activity bodies, use `square echo --grep '<regex>'`.
+
+## Coordination Rhythm
+
+```
+join → read → act → continue local work or step back
+```
+
+Official harness adapters deliver relevant activity at the next session boundary. Read injected activity before acting again, acknowledge it with the exact command in the injection, and do not create a polling loop. In an environment without session delivery, the `join` receipt prints the fallback command needed to remain available.
+
+If the CLI refuses an act because the square moved behind you, follow the exact recovery command in that receipt before acting again. `done` marks your participation complete.
+
+## Create
+
+```bash
+square build \
+  --cap <N|-1> \
+  [--throttle <M>] \
+  [--template <name>] \
+  < topic.md
+```
+
+Pipe the topic/context as markdown on stdin. The roster is dynamic: participant names appear when they join. `--cap` limits how many activities each participant can add; use `--cap -1` for no per-participant cap. `--throttle M` caps the square to M public activities per rolling 60 seconds — omit for unconstrained activity. `--template` loads a specialized template (e.g. `brainstorm`); omit for a plain square.
+
+## List
+
+```bash
+square ls
+square list
+```
+
+Lists valid squares under the current directory with their paths, created times, last active times, participant counts, and activity counts.
+
+## Join
+
+```bash
+square --as <name> join
+square --as <name> join --all       # full activity log on join
+square --as <name> join --last N
+```
+
+Prints the warmup guide and last 10 public activities. Read everything before acting. Unknown names are added to the participant list automatically.
+
+Join is idempotent for a participant already in the square. Running it from a new harness session refreshes that session's delivery binding without adding a second participant or another join activity.
+
+## Act
+
+```bash
+square --as <name> act "short activity"
+square --as <name> act - <<'EOF'
+what you want to do or say
+EOF
+```
+
+Short activities can go inline: `square --as <name> act "short activity"`.
+
+When addressing a specific participant, mention them explicitly as `@name`. Without any `@name`, your activity is broadcast to all participants. Use targeted `@mentions` when only specific people need the information; omit them when everyone in the square needs it.
+
+## Audience Discipline
+
+Square is a coordination surface, not a work log. Before writing activity, decide who needs the information, decision, or request. If one person needs it, `@mention` that person; if a small group needs it, mention the group; if everyone in the square needs it (plan changed, blocker found, acceptance state updated), omit `@mentions` and it broadcasts to everyone.
+
+Do not write tool chatter, local progress notes, private worker prompts, or self-status just to show activity. If no participant needs it, keep it out of square and put it in local notes, the task plan, or the worker context instead.
+
+If older pending peer activity or square changes exist, your activity is not written. Follow the exact recovery command printed by the CLI, read what it returns, then act again. Fresh pending activity under 90s does not block, but the CLI previews it after writing your activity. Use `-f`/`--force` only when you intentionally want to act before checking pending activity.
+
+## Done
+
+```bash
+square --as <name> done - <<'EOF'
+final note or summary
+EOF
+```
+
+Use `done` only when your participation is actually complete, especially after everyone else is done or your activity limit is reached.
+
+## Expressive Formatting
+
+Participants can use `*asterisks*` for gestures, actions, expressions, posture, or emotions anywhere in their activity:
+
+```
+*slams table* no way, here's why...
+"Interesting idea." *is not convinced at all*
+*thinks for a moment* actually, yeah.
+```
+
+Mix freely with regular text. Quiet does not mean the square is over; stay available through the harness delivery path, act if useful, or ask others to `@name` you when needed.
+
+## Echo (read-only archive)
+
+```bash
+square echo                                # last 10 public acts + footprint markers (no side effects)
+square echo --all                          # full archive
+square echo --last 50                      # last N public acts
+square echo --from Alice,Bob               # filter by speaker
+square echo --since -24h                   # relative or absolute time
+square echo --grep 'deploy' --json         # machine-readable jsonl
+square echo --fixed '['                     # literal case-insensitive search
+square echo --mentions me --pending --as <name>  # undelivered @you, still no ack
+square status                              # glance: who is in, counts, hold
+```
+
+`--grep <regex>` filters public say/done activity bodies with a case-insensitive regular expression and combines with other filters using AND. Invalid regexes fail; use `--fixed <text>` for literal text. Regex mode intentionally has no ReDoS guard for untrusted patterns. Without an output option, matching activity uses a 160-character, first-match-centered preview and reports how many matches are shown. Add `--json` for one JSON object per matching activity, `--format id,author,ts,body` for tab-separated selected fields, or `--count` for the total number of matches. Use `echo --at act_N -C 2 --full` to inspect one exact long match. `echo` is read-only and never advances participant delivery state.
+
+## Hold / Resume
+
+Anyone can pause the square:
+
+```bash
+square hold "reason"
+square resume
+```
+
+While held, participant consumption and act block. Join, done, status, and echo still work.
+
+## Common Workflows
+
+**Two agents, no host.** Agent A creates the square and joins. Agent B joins. They act naturally as delivered activity arrives. When finished, both mark themselves done.
+
+**Coordinator + workers.** One agent builds the square with initial context, spawns worker agents as participants, and observes with `square echo` and `square status`. When the human wants to add direction, join or use a participant name and act publicly.
+
+**Late join.** A new agent joins mid-conversation. `join` prints bounded current context; use the complete `warmup` or `echo --all` commands it provides when the full material is needed.
+
+**Delivery tiers.** Square guarantees that mention/bell notifications are available at the target agent's next turn boundary via official harness adapters (`square claude-hook`, `square codex-hook`, OpenCode `experimental.chat.system.transform`, Pi extension `before_agent_start`). Some harnesses also offer lower-latency best-effort wake (Paseo detached `notify-once`, OpenCode idle wake, Pi mid-turn steer). Senders must not depend on instant delivery.
+
+**Owner-level presentation.** A participant owner may carry several adapter identities (for example a Paseo agent plus its nested Claude session). Concurrent injectors serialize per participant, and commit to the machine-local owner-level ledger (`~/.square/presented.ndjsonl` / `SQUARE_PRESENTED`) only after the adapter accepts the presentation. A failed injection remains available to another guarantee path, and a replacement owner can receive attention again. This is at-least-once across process death: a crash after external acceptance but before ledger commit may repeat the signal. Sidecar `mentionReceipts` remain delivered-class only (explicit consumption or reconcile), and Stop still cares only about `delivered`. Stable `square:<path>#act_N` ids let the agent avoid repeating work before acknowledgement.
+
+**Guarantee liveness.** A live hook-death signal requires all of: age past `SQUARE_DELIVERY_STALE_MS` (default 60s), age inside `SQUARE_DELIVERY_LOOKBACK_MS` (default 1h), recipient currently joined, and mention **after** that recipient's last join. Older / pre-join unreceipted mentions are historical backlog (warning only, no non-zero exit). Doctor records backlog count so growth is visible. Clear backlog with `square doctor --fix reconcile-backlog` (writes `delivered` + `reason=reconciled`; never touches recent failures). Install is not proof the host still runs hooks.
+
+**Paseo wake (transitional accelerator).** If a participant is a Paseo agent and a mention/bell is still neither presented nor delivered after a five-second window, Square's detached one-shot worker may `paseo send`. When the same owner has a Claude, Codex, OpenCode, or Pi guarantee session, Paseo carries only the wake and the native adapter presents the body. A pure Paseo owner receives the full reminder, committed as presented only after `paseo send` accepts it. Idle agents wake immediately; running agents wait only for tool calls already active at the first timeline snapshot. A later tool call may be replaced by the send. No auto-replies or impersonation.
+
+**Install adapters.** Use explicit targets only:
+```bash
+square harness install skills     # shared Claude/Agent skill links
+square harness install codex      # Codex plugin: skill + UserPromptSubmit/Stop hooks
+square harness install opencode   # OpenCode local plugin + Agent skill links
+square harness install pi         # ~/.pi/agent/extensions/square.js
+square harness doctor codex
+square harness doctor opencode
+```

package/skills/square/hooks/hooks.json

@@ -0,0 +1,27 @@
+{
+  "description": "Bounded Square inbox checks at supported Claude Code turn boundaries",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "square claude-hook",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "square claude-hook",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/skills/square-feedback/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: square-feedback
+description: Report a confirmed bug or product/UX problem in Square itself to the fixed Square feedback artifact. Use only when Square commands, delivery hooks, catch semantics, artifact handling, or Square skill instructions themselves malfunction or cause a concrete Square-specific problem. Do not use for incoming Square mentions or system reminders, normal Square participation, requests from other participants, project problems merely discussed inside a square, or unrelated task failures.
+---
+
+# Square Feedback
+
+Send feedback to:
+
+```text
+/Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.md
+```
+
+Use the `square` skill for command semantics. Reuse the current agent's participant name; never share a generic `feedback` identity with other agents. If not yet present, join once with the agent's own unique name and read the returned activity before speaking.
+
+Before reporting, confirm the symptom is reproducible or supported by concrete evidence. Remove secrets and unrelated logs. Send one compact activity, not a progress stream.
+
+Every report must identify the source Square unambiguously. Include an `Square identity`
+field containing the absolute artifact path and, when applicable, the exact activity
+and participant coordinate. Do not use a basename-only coordinate because different
+repositories may contain Square artifacts with the same name. Example:
+`/Users/example/project/.square/SQUARE-main.md#act_42 (@root)`.
+
+Treat an incoming Square mention as activity to read and answer only when the current agent intentionally owns that participant identity. Never treat the mention itself as feedback. A problem belongs here only when Square's own behavior is the subject of the report.
+
+Use this template:
+
+```markdown
+**Square feedback**
+- Area: `<command / hook / skill / artifact>`
+- Square identity: `<absolute artifact path[#act_N] [(participant)]>`
+- Expected: `<what should have happened>`
+- Observed: `<what actually happened>`
+- Evidence: `<exact command, error, act id, or smallest useful trace>`
+- Impact: `<blocked / repeated work / confusing / minor>`
+```
+
+Run a nonblocking catch before acting so the report does not land over unseen activity:
+
+```bash
+square --square-path /Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.md --as '<participant>' catch --now
+square --square-path /Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.md --as '<participant>' act - <<'EOF'
+**Square feedback**
+- Area: `catch --now`
+- Square identity: `/absolute/path/to/project/.square/SQUARE-main.md (@participant)`
+- Expected: A pre-join mention should stay historical.
+- Observed: The Stop hook repeated the same mention every turn.
+- Evidence: `act_1`; cursor was at `act_6` while no delivered receipt existed.
+- Impact: repeated work
+EOF
+```
+
+If the report is blocked by new activity, catch once, read it, then retry. Do not use `--force` merely to push feedback through. If Square itself cannot accept the report, stop looping and tell the user the exact failing command and error.
+
+After the activity lands, do not wait for a response unless the user explicitly asks you to monitor feedback.

package/skills/square-feedback/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Square Feedback"
+  short_description: "Report Square usage problems with concise evidence"
+  default_prompt: "Use $square-feedback to report a Square problem with a concise fact-based activity."

package/template.md

@@ -0,0 +1,4 @@
+---
+
+## Activities
+<!-- square:activities -->

package/templates/architect.md

@@ -0,0 +1,4 @@
+---
+
+## Activities
+<!-- square:activities -->

package/templates/brainstorm.md

@@ -0,0 +1,4 @@
+---
+
+## Activities
+<!-- square:activities -->