hideki5123 grill-to-impl
Bridge a finished design conversation to a running implementation session.
Pipeline:
grilled session → synthesize brief → team hardening → codex-server review loop
→ write brief file → confirm → launch bg prd-council session
The terminal action launches a fresh, autonomous, remote-controllable Claude
Code session (via the user's claude-bg background launcher, ccb-style) that
runs /prd-council seeded with the brief. prd-council then drafts the PRD,
debates it with Codex, and emits the execution-ready doc set + task list under
docs/prd/<slug>/ — kicking off implementation.
This skill generates a prompt/brief and spawns a session. It does NOT write the feature code itself — the spawned session does.
Relationship to neighboring skills
grill-me— runs BEFORE this; produces the shared understanding this consumes.prd-council— what the spawned session RUNS; it grills + Codex-debates + emitsdocs/prd/<slug>/. This skill seeds it so it does not re-grill from scratch.handoff/session-handover— compact a session into a doc; this skill goes further: it reviews with Codex and launches the next session.to-prd— publishes a PRD to a tracker; out of scope here (local + spawn only).
Do not duplicate prd-council's heavy debate — the Codex step here is a
pre-flight hardening of the brief, not a full PRD debate.
Feedback Check
If feedback/log.md exists and has 5 or more entries, read the last 10. If a
pattern is apparent (same issue in 3+ entries, or average rating below 3):
- Tell the user (in Japanese): 「繰り返しのフィードバックを検出: [簡潔に]。
/skill-improve --skill grill-to-implで改善案を分析できます。」 - Continue with normal execution either way.
If feedback/log.md does not exist, skip silently.
Arguments
Parse from the invocation. All optional.
| Argument | Default | Meaning |
|---|---|---|
--session <id> |
current session | Source of the grilled content. Default: synthesize from the CURRENT conversation context. Pass an id to pull from a prior session transcript instead. |
--target <path> |
current repo root | Project the spawned session runs in (where docs/prd/<slug>/ lands and code is built). |
--slug <slug> |
derived from the brief title | Feature slug for paths / the session label. |
--lang <auto|ja|en> |
auto |
Brief + downstream doc language. Commit messages stay English. |
--model <opus|sonnet|haiku> |
inherit (ccb default) | Model for the spawned bg session. |
--rounds <N> |
3 |
Cap on codex-server review rounds before proceeding with the best brief. |
--no-codex |
off | Skip the Codex loop; run a Claude-only self-critique and mark the brief degraded. |
--no-team |
off | Skip the agent-team hardening pass. |
--auto-launch |
off | Skip the confirmation gate and launch immediately after Codex approval. |
Workflow
1. Capture the grilled content
- Default (
--sessionunset): synthesize from the CURRENT conversation — extract every resolved decision, non-goal, constraint, file/line anchor, risk, and open question surfaced during the grill. Do not invent; only capture what was decided. --session <id>given: load that transcript (use the session search/recap MCP tools) and extract the same.- If the current context shows no finished design discussion AND no
--session, stop and ask the user what to hand off (do not fabricate a brief).
2. Synthesize the brief
Read references/brief-template.md and write the brief to that structure. The
brief MUST be self-contained — the spawned session has none of this conversation's
context. Mirror the depth of a strong handoff: concrete file:line anchors, a
locked-decisions table, explicit non-goals, branch setup, acceptance criteria,
risks, and a closing "Seed for prd-council" block.
3. Team hardening (skip if --no-team)
Create an agent team to explore the draft brief from different angles:
Brief Fidelity, Implementability, Idempotence & Safety. Read
references/brief-review-team.md for the teammate prompts and the synthesis
protocol. Fold Critical/Important findings back into the brief before Codex sees it.
4. Codex review loop
Read references/codex-review-loop.md. Run a codex-server structured review of
the brief, looping until Codex approves or --rounds is hit. Each round: send the
current brief, get a structured verdict (approved + blocking_issues + suggestions),
and revise the brief from the blocking issues. The verdict schema must list ALL
properties in required or codex-server returns HTTP 400 on round 1. If Codex is
unavailable or --no-codex, degrade to a Claude-only self-critique and mark the
brief > Codex review: DEGRADED (Claude-only).
5. Write the brief file
Write the final brief to <target>/docs/design/<slug>-impl-brief.md (create dirs).
This file is what the spawned session reads.
6. Confirm launch (skip if --auto-launch)
Show the user: the brief path, the resolved --target/--slug/--model, and the
EXACT launch command. Get an explicit go-ahead before spawning. Launching an
autonomous, permission-bypassing background agent is consequential — gate it by
default. --auto-launch skips this.
7. Launch the bg prd-council session
Run scripts/launch_council_session.sh (read references/launch-and-handoff.md
for the contract). It prefers the user's claude-bg (adding ccb flags
--permission-mode auto --allow-dangerously-skip-permissions), falls back to a
replicated claude --bg --remote-control … --permission-mode auto --allow-dangerously-skip-permissions invocation, and as a last resort prints the
command for the user to run. The spawned session's initial prompt reads the brief
and invokes /prd-council --slug <slug> --out docs/prd/<slug>/ --lang <lang>,
instructing it to treat the brief as already-grilled requirements.
8. Report
Tell the user: the brief path, the spawned session's remote-control label
(<slug>-<sid8>), and how to attach — the Claude app's Remote Control list, or
ccon <sid8> / claude --resume <sessionId>. Note that prd-council's residual
questions will surface there for the user to answer remotely.
Retrospective
After step 8, reflect on the run:
- Consider: mid-session corrections, rejected briefs, Codex/launcher errors, missing anchors discovered late?
- Ask the user (in Japanese): 「今回のハンドオフのフィードバック (1-5、気になった点、なければEnter)」
- If the user gives feedback OR corrections/issues occurred:
a. Create
feedback/next to this SKILL.md if missing. b. Read/createfeedback/log.md(# Feedback Logheader + the append-at-top comment). c. Prepend an entry using the log format inreferences/skill-improvement-guide.mdof the my-skill-factory skill (timestamp, version, task, outcome, corrections, issues, user note). d. Confirm in one short Japanese sentence. - If the user skips AND nothing went wrong, end without recording.
Dependencies
- codex-server skill (preferred) for the structured review loop — uses the
user's ChatGPT subscription via
codex login. Degrade gracefully if absent. - claude-bg on PATH (the user's background launcher) for spawning. Degrade to
claude --bgor to printing the command if absent. - prd-council skill — invoked by the spawned session.
- Optional: session search/recap MCP tools when
--session <id>is used.
Behavior Scenarios
Scenario: Hand off the current grill to a new implementation session
Given the current conversation just finished a grill-me design with locked decisions
When the user runs /grill-to-impl
Then it synthesizes a self-contained brief, hardens it with the agent team,
loops codex-server review until approval, writes the brief file, shows the
launch command for confirmation, and on go-ahead spawns a claude-bg
prd-council session, then reports the remote-control label
Scenario: Codex is unavailable
Given codex login / codex-server is not available
When the review step runs
Then it degrades to a Claude-only self-critique, marks the brief DEGRADED,
and continues without silently skipping review
Scenario: claude-bg is not installed
Given the launcher cannot find claude-bg or claude --bg fails
When step 7 runs
Then it prints the exact launch command for the user to run manually
instead of failing the whole workflow
Scenario: Fully automatic launch
Given the user passes --auto-launch
When Codex approves the brief
Then the session is spawned immediately without the confirmation gate
Scenario: Source is a prior session
Given the user passes --session <id>
When capturing content
Then it loads that transcript via session tools and synthesizes the brief from it
rather than the current context
Scenario: Nothing to hand off
Given the current context has no finished design discussion and no --session
When the user runs /grill-to-impl
Then it stops and asks what to hand off instead of fabricating a brief
Scenario: Brief fidelity gap found by the team
Given the draft brief dropped a non-goal or constraint decided during the grill
When the team hardening pass runs
Then the Brief Fidelity teammate flags the omission and it is restored before Codex review
References
references/brief-template.md— structure of the self-contained implementation brief.references/codex-review-loop.md— codex-server structured review protocol, verdict schema (all-required), round cap, graceful degradation.references/brief-review-team.md— the Brief Fidelity / Implementability / Idempotence & Safety teammate prompts + synthesis protocol.references/launch-and-handoff.md— claude-bg / ccb launch semantics, the prd-council seed prompt, fallbacks, attach instructions.