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
+-----------------------+
| $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:
+----------------+
| 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:
- Broadcast the current alignment brief to selected participants.
- Each participant states what they believe the task is.
- Each participant lists facts they know that others may not know.
- Each participant lists assumptions, contradictions, and questions.
- Merge questions into blocking and non-blocking sets.
- Route questions to the party that can answer them.
- Update the brief.
- 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:
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:
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:
skills/align/run.sh compile-round --round 1
Lock only after blocking questions are resolved:
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.
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:
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:
# 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 --briefthrough the real memory skill- project-agent response ingestion through
$align add-response $dogpile searchwith the generated alignment request as context$ask webgptagainst the authenticated browser-backed WebGPT path- final
alignment_lock.jsoncreation only after those receipts validate
Run it only when the local workstation has memory, dogpile credentials/search, Chrome, and an authenticated ChatGPT session:
ALIGN_LIVE_E2E=1 skills/align/sanity-live.sh
Optional controls:
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
.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
round-001-dogpile-request.md
round-001-webgpt-request.md
round-001-webgpt-ask-command.sh
/mnt/storage12tb/skills/align/live-e2e/<timestamp>/
report.json
memory.stdout
dogpile.stdout
webgpt.stdout
ask-runs/<ask_id>/
Stop Conditions
Set ready_for_execution: true only when:
- no blocking questions remain open
- the agreed goal and non-goals are explicit
- the output shape is concrete
- the acceptance criteria are testable or reviewable
- the source context is named
- the human or delegated owner approved the lock
Set ready_for_execution: false when:
- blocking questions remain
- WebGPT,
$scillm,$ask, or project knowledge contradict the brief - the output shape is still abstract
- a participant exposed missing source evidence
- the requested next step would produce a receipt instead of solving the real task
Common Mistakes
- Do not use
$alignas a substitute for$interview; use interview when the missing information is purely human preference or acceptance criteria. - Do not use
$alignas a substitute for$review-code,$review-plan, or$plan-iterate; alignment happens before those skills. - Do not summarize WebGPT or
$askmanually. Use their real runtimes and store artifact paths or reviewer text. - Do not call an alignment lock complete because a reviewer passed it. The project agent must merge the result and clear blocking questions.