align

# Align Use `$align` to equalize context before action. The skill exists for tasks where the human, project agent, WebGPT, `$scillm`, `$ask`, `$dogpile`, `$memory`, or `$project-knowledge` may each know different facts. It produces an `alignment_lock.json` that later skills can execute from. Do not use `$align` to implement, render, refactor, or review final work. It is a pre-execution gate. No code, infographic, dashboard, plan-iterate phase, or project-infographic render should start until the alignment lock says `ready_for_execution: true`. ## Core Rule Alignment is complete only when all blocking questions are answered and the lock records: - agreed goal - agreed non-goals - source context - participant facts - remaining assumptions and risks - output shape - acceptance criteria - explicit ready/not-ready decision If disagreement remains, keep the lock `ready_for_execution: false`. ## Participants Use only participants that are relevant to the task: | Participant | Role | |---|---| | `human` | Intent, preferences, domain nuance, acceptance bar | | `project_agent` | Local repo state, constraints, executable next steps | | `project_knowledge` | Durable project history and takeover notes | | `memory` | Prior lessons and similar solved problems | | `scillm` | Direct model critique through the localhost LLM proxy | | `ask` | Ask/oracle/deep-review runtime with artifacts; owns WebGPT routing | | `dogpile` | Fresh external research when local context is insufficient | | `webgpt` | Browser/session-visible context and human-facing judgment | WebGPT calls must route through `$ask webgpt`; `$ask` already owns the WebGPT oracle backend and uses `surf webgpt.submit --no-activate` against the user's authenticated ChatGPT tab. `$align` does not call `surf` directly. Do not send WebGPT requests through `$scillm`; `$scillm` is for direct model calls such as `gpt-5.5`, Gemini, Claude, or OpenCode Go. Preserve the tab id when the human provides it. Use `$dogpile` only when alignment is blocked by missing external/current knowledge. Do not use it for facts that `$project-knowledge` or `$memory` already answer. ## Runtime Routing ```text +-----------------------+ | $align init | | goal, output, sources | +-----------+-----------+ | v +-----------------+-----------------+ | Round N: alignment_brief | | participants state facts, gaps, | | contradictions, and questions | +-----------------+-----------------+ | +-----------------+-----------------+ | compile-round extracts questions | | Question[blocking/nonblocking]: | +-----------------+-----------------+ | open blocking questions? | yes | no v v +----------------+----------------+ +-------+--------+ | route each question to owner | | lock --ready | | human/project/memory/reviewer | | writes lock | +----------------+----------------+ +----------------+ | v +----------------+----------------+ | add-response / answer-question | | update brief, increment round | +----------------+----------------+ | v Round N+1 ``` Reviewer routes are optional inputs to a round: ```text +----------------+ | Round N brief | +-------+--------+ | +-----------------------------+-----------------------------+ | | | v v v +--------------------+ +--------------------+ +--------------------+ | WebGPT via $ask | | $scillm direct | | $ask review/oracle | | prepare-review | | prepare-review | | prepare-review | | --reviewer webgpt | | --reviewer scillm | | --reviewer ask | +---------+----------+ +---------+----------+ +---------+----------+ | | | v v v skills/ask/run.sh ask webgpt round-N-scillm-request.json round-N-ask-request.md --webgpt-tab-id <id> model: gpt-5.5 skills/ask/run.sh ask | reasoning_effort: high --deep-review v optional persona prompt $ask -> surf webgpt.submit | --no-activate v | POST localhost:4001/v1/chat/completions v authenticated ChatGPT tab External/current research: prepare-review --reviewer dogpile -> round-N-dogpile-request.md Use only when missing external facts block alignment. ``` ## Round Loop Each round follows the same sequence: 1. Broadcast the current alignment brief to selected participants. 2. Each participant states what they believe the task is. 3. Each participant lists facts they know that others may not know. 4. Each participant lists assumptions, contradictions, and questions. 5. Merge questions into blocking and non-blocking sets. 6. Route questions to the party that can answer them. 7. Update the brief. 8. Stop only when blocking questions are resolved or max rounds is reached. If max rounds is reached with blocking questions open, stop with `ready_for_execution: false` and surface the smallest human decision needed. ## CLI ### WebGPT tab binding (CLI parity) Prefer **zero-flag** `$ask webgpt` from a registered working directory. `/ask` composes `$browser-oracle` automatically. `init` and `prepare-review` persist binding hints in `.align/state.json` and emit the same flags on generated `round-*-webgpt-ask-command.sh`. | Flag | When to use | |------|-------------| | *(none)* | cwd has walk-up registry + binding — preferred | | `--browser-oracle-from <dir>` | Override walk-up root (monorepo subdir) | | `--webgpt-project <name>` | Explicit project; skips yaml walk-up | | `--webgpt-tab-id <id>` | One-off override; skips walk-up | | `--webgpt-url <url>` | Resolve by conversation URL; skips walk-up | **Resolution order** (same as `$ask` / `$surf`): `--webgpt-tab-id` → `--webgpt-url` → `$browser-oracle` walk-up → `--webgpt-project` → one `chatgpt.com` tab (fail-closed). Setup: `$browser-oracle register` + `bind` + `doctor --from <dir>`. See `$browser-oracle` and `$ask` SKILL.md **WebGPT tab binding** sections. Run from the repository or project root that owns the task: ```bash skills/align/run.sh init \ --goal "Create a clear plan-iterate infographic request" \ --output-shape "source-derived storyboard and web infographic request" \ --participant human \ --participant project_agent \ --participant project_knowledge \ --participant scillm \ --participant ask \ --participant dogpile \ --participant webgpt # Prefer zero-flag from a registered dir, or persist walk-up root: # --browser-oracle-from skills/oc-subagent/personas/mathematics # Legacy explicit override: # --webgpt-tab-id 837343529 ``` Record participant responses: ```bash skills/align/run.sh add-response \ --participant project_agent \ --round 1 \ --text "Task: reconcile the workflow before rendering. Fact: the prior visual failed because there was no approved storyboard. Question[blocking]: what exact sample project should anchor the visual?" ``` Compile the round: ```bash skills/align/run.sh compile-round --round 1 ``` Lock only after blocking questions are resolved: ```bash skills/align/run.sh lock --ready --approved-by human ``` ## Reviewer Request Generation `prepare-review` creates replayable request artifacts for reviewers. It does not call the reviewer by itself. ```bash skills/align/run.sh prepare-review --round 1 --reviewer scillm skills/align/run.sh prepare-review --round 1 --reviewer ask skills/align/run.sh prepare-review --round 1 --reviewer dogpile skills/align/run.sh prepare-review --round 1 --reviewer webgpt --browser-oracle-from skills/oc-subagent/personas/mathematics # or: --webgpt-tab-id 837343529 ``` Use WebGPT when the review needs the human's authenticated ChatGPT browser session or browser-visible context. Use `$scillm` when the review should be a direct, replayable model call, for example GPT-5.5 high reasoning with a persona/system prompt: ```bash skills/align/run.sh prepare-review \ --round 1 \ --reviewer scillm \ --scillm-model gpt-5.5 \ --reasoning-effort high \ --persona-prompt "You are a skeptical product alignment reviewer. Focus on mismatched assumptions and missing acceptance criteria." ``` Recommended calls after `prepare-review`: ```bash # scillm direct review .align/reviews/round-001-scillm-command.sh # ask deep review or WebGPT oracle skills/ask/run.sh ask "Review the alignment request at .align/reviews/round-001-ask-request.md" \ --deep-review --deep-review-target .align/reviews/round-001-ask-request.md skills/ask/run.sh ask webgpt "Review the alignment request at .align/reviews/round-001-webgpt-request.md" \ --browser-oracle-from skills/oc-subagent/personas/mathematics --oracle-iterations 1 # dogpile research only if alignment is blocked by missing external facts skills/dogpile/run.sh search "facts needed to unblock this alignment" \ --context-file ".align/reviews/round-001-dogpile-request.md" ``` Store the resulting reviewer text with `add-response`. Reviewer receipts are inputs to alignment; they are not execution approval by themselves. ## Live Composition Sanity `sanity.sh` is the fast local check. It proves the round loop, blocking-question gate, reviewer request generation, and lock schema without spending external quota. `sanity-live.sh` is the required real-world E2E gate before claiming `$align` is ready as a composite skill. It is opt-in because it calls live downstream systems: - `$memory recall --brief` through the real memory skill - project-agent response ingestion through `$align add-response` - `$dogpile search` with the generated alignment request as context - `$ask webgpt` against the authenticated browser-backed WebGPT path - final `alignment_lock.json` creation only after those receipts validate Run it only when the local workstation has memory, dogpile credentials/search, Chrome, and an authenticated ChatGPT session: ```bash ALIGN_LIVE_E2E=1 skills/align/sanity-live.sh ``` Optional controls: ```bash ALIGN_LIVE_E2E=1 \ ALIGN_WEBGPT_TAB_ID=837343529 \ ALIGN_LIVE_OUTPUT_ROOT=/mnt/storage12tb/skills/align/live-e2e \ skills/align/sanity-live.sh ``` If no `ALIGN_WEBGPT_TAB_ID` or `ALIGN_WEBGPT_PROJECT` is provided, the live check passes `--webgpt-create-tab` to `$ask`; this still requires a valid local Chrome/WebGPT setup. The proof artifact is `/mnt/storage12tb/skills/align/live-e2e/<timestamp>/report.json` by default. Skipped live checks do not establish readiness. ## Artifact Layout ```text .align/ alignment_state.json alignment_brief.md alignment_lock.json rounds/ round-001/ participant-human.md participant-project_agent.md participant-scillm.md round_summary.md questions.json reviews/ round-001-scillm-request.json round-001-scillm-command.sh round-001-ask-request.md