Generate a Plan Brief HTML for non-engineer vibecoders before implementation starts. Searches harness-mem (project-only) for relevant past decisions, patterns, and Plans archive entries, then renders a single-file HTML artifact summarizing understanding, options, risks, acceptance criteria, and confidence. Use when the user requests a planning preview, a non-engineer-friendly summary before approval, or says: plan brief, planning preview, planning overview, plan review. Do NOT load for: actual implementation, code review, release work.
Instrucciones de origen · Vista previa de solo lectura
name
harness-plan-brief
description
Generate a Plan Brief HTML for non-engineer vibecoders before implementation starts. Searches harness-mem (project-only) for relevant past decisions, patterns, and Plans archive entries, then renders a single-file HTML artifact summarizing understanding, options, risks, acceptance criteria, and confidence. Use when the user requests a planning preview, a non-engineer-friendly summary before approval, or says: plan brief, planning preview, planning overview, plan review. Do NOT load for: actual implementation, code review, release work.
description-en
Generate a Plan Brief HTML for non-engineer vibecoders before implementation starts. Searches harness-mem (project-only) for relevant past decisions, patterns, and Plans archive entries, then renders a single-file HTML artifact summarizing understanding, options, risks, acceptance criteria, and confidence. Use when the user requests a planning preview, a non-engineer-friendly summary before approval, or says: plan brief, planning preview, planning overview, plan review. Do NOT load for: actual implementation, code review, release work.
allowed-tools
["Read","Write","Edit","Bash"]
argument-hint
[task-description]
user-invocable
true
harness-plan-brief
A skill for non-engineer clients and producers that presents Claude's plan for an upcoming task as a single HTML page.
Used at cognitive load peak (1): the plan comprehension stage.
Quick Reference
"Create a Plan Brief" → this skill
"Give me a rough overview before implementation" → this skill
"Show the plan in a non-engineer-friendly way" → this skill
Responsibility Boundaries
Scope
This skill's responsibility
Search
Current project only (always specify project: <current>, strict_project: true)
Cross-project
Not performed (opt-in via --cross-project-group <name> flag from Phase 65.3 onward)
Write
Not performed (memory write after Plan Brief approval is the responsibility of plan-brief-record-decision.sh)
Confidence calculation
Delegated to scripts/plan-brief-compile.sh implemented in 65.1.3
Input
Pass the user's request as the [task-description] argument.
If no argument is provided, accept interactively.
Important: The project parameter is required. Never pass an empty string or null.
Specify strict_project: true and never perform cross-project searches.
You may filter by tags for decision / pattern, but project is fixed.
Retrieve up to 5 similar cases from past decisions (D1-D41) / patterns (P1-P33) / 28 Plans archive entries.
Only when the --cross-project-group <name> flag is present:
Follow D43 Option α (MCP N-call) to perform cross-project search:
# (a) Resolve group → member projects (yaml SSOT)
MEMBERS_JSON="$(bash scripts/load-cross-project-groups.sh --group "<name>" 2>/dev/null)" || {
echo"ERROR: cross-project group not found: <name>" >&2
exit 1
}
# MEMBERS_JSON is a JSON array in ["proj1","proj2",...] format
If MEMBERS_JSON is [] (empty array), show a warning and fall back to default single project search.
If MEMBERS_JSON is non-empty, issue one MCP search per member project:
for each project in MEMBERS_JSON:
mcp__harness__harness_mem_search(
project: <member>,
strict_project: true,
query: <user request>,
expand_links: true,
limit: 5
)
Merge, dedupe (by id), and sort by relevance_score descending on the client side, then narrow to a maximum of 5 entries.
Note that the total number of calls increases (e.g., 5 calls if the group has 5 projects), so latency will increase.
Basis for D43 Decision 1: The MCP tool schema does not expose projects: [array] or strict_project: false, so client-side N-calls are the only option for cross-project search.
For details, see "Phase 65.3 Implementation Decisions (D43)" in .claude/rules/cross-repo-handoff.md.
Cross-project results must pass through Layer 2/3 (Phase 65.3.2-65.3.4) redaction:
Use bash scripts/render-html.sh ... --with-redaction when rendering HTML
This ensures proper nouns do not leak through dictionary + NER + final scan (3 stages)
Step 3: Build the context JSON
Use scripts/plan-brief-compile.sh (implemented in Phase 65.1.3) to construct JSON conforming to the plan-brief-context.v1 schema from the mem search results.
Until 65.1.3 is implemented, Claude builds it directly with jq:
OS-specific dispatch via scripts/plan-brief-open.sh:
bash scripts/plan-brief-open.sh "$HTML_OUT"
When the BROWSER=true env is set (CI environment), opening is skipped and only the path is output via printf.
Step 6: Wait for user approval
Confirm "Is it okay to proceed with implementation based on this understanding?"
Memory write after approval is the responsibility of a separate skill (plan-brief-record-decision.sh in Phase 65.1.4).
Failure Behavior
Failure
Behavior
mcp__harness__harness_mem_search unreachable
Show warning and continue with related_decisions / similar_past_plans as empty arrays
git rev-parse --show-toplevel fails
Continue with PROJECT_NAME=current
render-html.sh fails
Output error to stderr and exit 1
plan-brief-open.sh fails
Only output HTML path to stdout and exit 0 (browser open is best-effort)
Related
scripts/render-html.sh (Phase 65.1.1) — HTML template engine
