harness-plan-brief

harness-plan-brief

A skill that presents the plan Claude is about to start on as a single HTML page for non-engineer requesters and producers. Used at the requester's cognitive load peak (1), the plan-understanding stage.

Quick Reference

「Create a Plan Brief" → this skill
「Roughly organize before implementation" → this skill
「Show me the plan for non-engineers" → this skill

Responsibility boundaries

Scope	Responsibilities of this skill
Search	Current project only (`project: <current>`, `strict_project: true` must always be specified)
Cross-project	Do not do (from Phase 65.3 onward, opt-in released via the `--cross-project-group <name>` flag)
Write	Not done (memory write after Plan Brief approval is the responsibility of `plan-brief-record-decision.sh` )
plan_readiness calculation	`scripts/plan-brief-compile.sh` Delegated to. The compatibility field name `confidence` is kept, but its meaning is limited to DoD clarity + dependency resolution rate

Input

Pass the user's request to argument [task-description] . If there are no arguments, receive it interactively.

Output

Output	Path	Format
Plan Brief HTML	`.claude/state/views/plan-brief-<timestamp>.html`	HTML that can be opened standalone (no server, no JS framework)
Plan Brief context JSON	`.claude/state/views/plan-brief-<timestamp>.context.json`	`plan-brief-context.v1` schema

Schema: `plan-brief-context.v1`

{
  "schema": "plan-brief-context.v1",
  "user_request": "string (ユーザーの request 原文)",
  "my_understanding": "string (Claude の理解を 1-3 段落で)",
  "options": [
    { "name": "string", "summary": "string", "pros": ["string"], "cons": ["string"] }
  ],
  "risks": [
    { "kind": "string", "severity": "info|warn|critical", "description": "string", "mitigation": "string" }
  ],
  "acceptance_criteria": [
    { "id": "string", "description": "string", "verifiable_by": "string" }
  ],
  "tdd_required": "yes|no|skip:<reason>",
  "confidence": 0,
  "confidence_evidence": ["string (plan_readiness evidence: DoD clarity + dependency resolution only)"],
  "related_decisions": [
    { "id": "string", "title": "string", "relevance": "string" }
  ],
  "similar_past_plans": [
    { "archive_path": "string", "phase": "string", "outcome": "cc:完了|cc:WIP|cc:TODO|skipped", "relevance": "string" }
  ],
  "project": "string",
  "generated_at": "ISO8601"
}

For the complete schema, refer to schemas/plan-brief-context.v1.schema.json .

Execution Flow

When the skill is invoked, Claude operates according to the following steps.

Step 1: Resolve the project name

PROJECT_NAME="$(basename "$(git rev-parse --show-toplevel)")"

PROJECT_NAME If is empty (outside git), use current as the default.

Step 2: harness-mem を project-only search with (default)

If the argument is --cross-project-group <name> flag がNone(default behavior):

mcp__harness__harness_mem_search を Always call with the following parameters:

project: <PROJECT_NAME>
strict_project: true
query: <user request>
expand_links: true
limit: 5

Important: project The parameter isRequired. An empty string or null must not be passed. strict_project: true Specify, andabsolutely never performcross-project searches. If necessary, tags filter で decision / pattern may be narrowed, butproject is fixed.

Retrieve up to 5 similar cases from past decisions (D1-D41) / patterns (P1-P33) / 28 Plans archives.

Step 2 (alt): cross-project search (Phase 65.3.5 opt-in)

Only if the argument is --cross-project-group <name> flag がYes:

Following D43 Option α (MCP N-call), perform cross-project search according to the following steps.

# (a) 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 は ["proj1","proj2",...] 形式の JSON 配列

MEMBERS_JSON が [] (empty array), issue a warning and fall back to the default single-project search.

MEMBERS_JSON If is non-empty,issue one MCP search for each member project Do:

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 in descending order of relevance_score on the client side for each search result , and narrow down to a maximum of 5. Since the total number of calls increases (5 calls if the group has 5 projects), note that latency will increase.

Basis for D43 Decision 1: The MCP tool schema has projects: [array] も strict_project: false is also not exposed, so cross-cutting search has client-side N-call as the only option. For details, refer to the "Phase 65.3 Implementation Decisions (D43)" in .claude/rules/cross-repo-handoff.md .

Cross-project results must always pass through Layer 2/3 (Phase 65.3.2-65.3.4) redaction:

When rendering HTML, bash scripts/render-html.sh ... --with-redaction is used
This ensures proper nouns are not missed across the three stages: dictionary + NER + final scan

Step 3: Assemble the context JSON

scripts/plan-brief-compile.sh using, from the mem search results plan-brief-context.v1 build a schema-compliant JSON.

From Phase 105.3 onward, the Plan Brief's confidence is a backward-compatible field name, and its displayed meaning is treated as plan_readiness . The calculation axes are fixed to only the following two.

DoD clarity: how many machine-verifiable numbers/conditions are included in the request / DoD
Dependency resolution rate: the proportion of similar Plans whose dependencies can be treated as completed

The success rate of past similar cases and the number of related Decisions / Patterns are displayed as context-only evidence, and are not added to the readiness score as a separate axis. This is to avoid misreading them as "AI comprehension" or "success probability".

options / risks / acceptance_criteria is always generated at least once. Even if mem search is empty, fill in at least the following.

options: at least one recommended proposal. Add alternatives as needed, with pros / cons
risks: at least one risk specific to this plan, such as readiness misreading, scope creep, or unobserved data
acceptance_criteria: at least one condition that can be machine-verified or visually checked after execution

Example:

jq -n \
  --arg req "$USER_REQUEST" \
  --arg proj "$PROJECT_NAME" \
  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  '{
    schema: "plan-brief-context.v1",
    user_request: $req,
    my_understanding: "(まだ未着手)",
    options: [{name:"Option A: 最小検証で進める", summary:"DoD と依存を先に確認してから実装", pros:["影響が小さい"], cons:["大きな再設計は別タスク化が必要"]}],
    risks: [{kind:"readiness-misread", severity:"warn", description:"plan_readiness を AI の理解度として誤読するリスク", mitigation:"DoD 明確度 + 依存解決率だけの指標として evidence に明記"}],
    acceptance_criteria: [{id:"AC-1", description:"Plan Brief context が非空の options / risks / acceptance_criteria を含む", verifiable_by:"tests/test-plan-brief-compile.sh"}],
    confidence: 0,
    confidence_evidence: ["plan_readiness DoD 明確度: 0/60", "plan_readiness 依存解決率: 0/40"],
    tdd_required: "no",
    related_decisions: [],
    similar_past_plans: [],
    project: $proj,
    generated_at: $ts
  }' > "$CONTEXT_JSON"

Step 4: Generate the HTML

scripts/render-html.sh (Phase 65.1.1) を templates/html/plan-brief.html.template call with:

In the HTML, display the TDD determination in one line. The format is tdd_required: yes、tdd_required: no, or tdd_required: skip:<reason> Set to either.

bash scripts/render-html.sh \
  --template plan-brief \
  --data "$CONTEXT_JSON" \
  --out "$HTML_OUT"

Step 5: Automatically open in the browser

scripts/plan-brief-open.sh dispatch by OS with:

bash scripts/plan-brief-open.sh "$HTML_OUT"

BROWSER=true If the env for is set (CI environment), open only outputs the path with skip is done printf .

Step 6: Wait for user approval

Confirm "is it okay to proceed with implementation based on this understanding?". The memory write after approval is the responsibility of a separate skill (Phase 65.1.4's plan-brief-record-decision.sh).

Behavior on failure

Failure	Behavior
`mcp__harness__harness_mem_search` not reached	Display a warning and continue with`related_decisions` / `similar_past_plans` as an empty array
`git rev-parse --show-toplevel` failure	`PROJECT_NAME=current` continue with
`render-html.sh` failure	Output the error to stderr and exit 1
`plan-brief-open.sh` failure	Just output the HTML path to stdout and exit 0 (browser open is best-effort)

scripts/render-html.sh (Phase 65.1.1) — HTML template engine
scripts/plan-brief-compile.sh (Phase 65.1.3) — context compilation
scripts/plan-brief-record-decision.sh (Phase 65.1.4) — approval memory write
harness-accept skill (Phase 65.2.1) — acceptance judgment skill (paired structure)
harness-progress skill (Phase 65.4.1) — progress management skill (paired structure)

About this skill

Quick Reference

Responsibility boundaries

Input

Output

Schema: `plan-brief-context.v1`

Execution Flow

Step 1: Resolve the project name

Step 2: harness-mem を project-only search with (default)

Step 2 (alt): cross-project search (Phase 65.3.5 opt-in)

Step 3: Assemble the context JSON

Step 4: Generate the HTML

Step 5: Automatically open in the browser

Step 6: Wait for user approval

Behavior on failure

Related

harness-plan-brief

About this skill

Quick Reference

Responsibility boundaries

Input

Output

Schema: plan-brief-context.v1

Execution Flow

Step 1: Resolve the project name

Step 2: harness-mem を project-only search with (default)

Step 2 (alt): cross-project search (Phase 65.3.5 opt-in)

Step 3: Assemble the context JSON

Step 4: Generate the HTML

Step 5: Automatically open in the browser

Step 6: Wait for user approval

Behavior on failure

Related

Schema: `plan-brief-context.v1`