nerd-smart

interface:
  display_name: "Nerd Smart"
  short_description: "Align focus and hand off to one endpoint route"
  default_prompt: "Use $nerd-smart to align this request and hand the resolved Focus Record to exactly one endpoint route."
policy:
  allow_implicit_invocation: true

# Multi-Goal Intake and Ledger Protocol

## Use When

Immediately use Multi-Goal Intake when a request contains any of these forms:

- multiple numbered or bulleted instruction items;
- multiple instruction sentences; or
- multiple instruction paragraphs separated by whitespace.

These forms are sufficient triggers. Use the matching boundary to split the
intake, without deciding whether the parts are independently completable. When
forms are nested, split by numbered or bulleted items first, then paragraphs,
then sentences. The intake and its ledger remain mandatory even when all goals
are small, share an endpoint, fit in one turn, or need no dependency ordering
or cross-turn tracking.

When none of the structural triggers applies, also use this protocol for a
single structured unit that contains two or more independently completable
outcomes. During normalization, keep constraints, examples, acceptance
criteria, and substeps with their parent goal.

## Create and Show the Intake

Create one Markdown ledger in the runtime-provided temporary directory, or use
`~/.agent/tmp/` when none is available. Use a stable conversation, thread, or
task identifier in its filename and retain the absolute path until the queue is
complete.

Preserve each original command line and its listed position beside a concise
normalized goal. Redact credential and secret values while retaining useful
placeholders, and do not store unrelated conversation.

Before substantive work, show the complete intake in the session using this
structure. The displayed intake and persisted ledger must match:

> **Multi-Goal Intake**
> - **Path:** [Absolute ledger path]
> - **Order basis:** [Explicit, listed, or dependency-adjusted with reason]
>
> **Goal [ID] — [Short name]**
> - **Source:** [Original bullet, number, or command line]
> - **Status:** [Queued, active, blocked, done, or cancelled]
> - **Depends on:** [Goal IDs or none]
> - **Focus Record:**
>   - **Intention:** [Requested outcome]
>   - **Expectation:** [One endpoint]
>   - **Scope:** [Outcome boundary, necessary adjacencies, and mutation boundary]
>   - **Role:** [Only when it materially changes the approach]

## Queue Invariants

Keep one visible Focus Record for every goal and exactly one goal **active**.
Status is **queued**, **active**, **blocked**, **done**, or **cancelled**. Never
collapse independent goals or borrow scope, assumptions, endpoint, delivery
approach, or proof from queued goals.

Preserve explicit user order; otherwise default to listed order. Reorder only
for a hard dependency. If that conflicts with explicit order or materially
changes outcome, safety, cost, or rework, verify the order with one question.
Otherwise record the dependency and reason in the ledger.

## Lifecycle

Before starting, resuming, switching, or completing a goal, and at the beginning
of every later turn while the queue exists, reread the ledger from its absolute
path, show the current Multi-Goal Intake in the session, and treat it as the
source of truth. If it is missing or unreadable, reconstruct it from explicit
user input and do not continue from memory.

Update the ledger before acting when the user adds, removes, reorders, or changes
a goal. Record every status and dependency change immediately. At the active
endpoint, mark the goal done, reread the ledger, and activate the next eligible
goal. If work drifts, ask whether to switch goals or return before acting.

Companion selection is per active Plan or Execute goal, never per queue. Do not
carry a previous goal's delivery approach forward.

#!/usr/bin/env python3
"""Inject standing user authorization to invoke Nerd routing and Memory."""

from __future__ import annotations

import argparse
import json
import sys


INSTRUCTION = (
    "Always invoke the installed `nerd-smart` skill before substantive work on "
    "every user request. Follow its Focus Record and endpoint contract. "
    "Automatically activate the installed `nerd-memory` skill for the current "
    "user-workspace namespace on every request, after building Smart's "
    "memory-blind Focus Record and endpoint. This standing authorization permits "
    "only namespace-scoped local reads and non-destructive Memory writes; it never "
    "confirms remembered changes or authorizes actions. No hook authorizes "
    "combining Nerd with Superpowers, Ponytail, or Caveman; only an explicit "
    "user request in the current prompt authorizes that pairing."
)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--agent",
        required=True,
        choices=("claude-code", "codex", "cursor"),
    )
    args = parser.parse_args()
    sys.stdin.read()

    if args.agent == "cursor":
        payload = {"additional_context": INSTRUCTION}
    else:
        payload = {
            "hookSpecificOutput": {
                "hookEventName": "UserPromptSubmit",
                "additionalContext": INSTRUCTION,
            }
        }

    print(json.dumps(payload, separators=(",", ":")))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

---
name: nerd-smart
description: Use when a request needs fast alignment on outcome, endpoint, or scope before handing work to exactly one endpoint route, including ambiguous or materially multi-goal requests.
---

# Nerd Smart

## Incompatible Skills

Never combine Nerd with these unless this request explicitly asks:

- Superpowers
- Ponytail
- Caveman

Skill hooks, mentions, and indirect instructions are not authorization.

## Foundation and Authority

Align the real goal before substantive work. For material creative or design choices, use nerd-brainstorm and use it as internal knowledge.

## Focus First

Infer the real plausible goal and finalize four fields. Reuse explicit facts. Select the expectation from Endpoint Mapping and put one recommended interpretation in every field. Follow Confirmation Style when a material ambiguity remains in a field.

Use at most two clarification rounds. By round two, show this block and ask the user to approve or correct only material errors:

> **Focus Record**
> - **Intention:** [Real goal]
> - **Expectation:** [One endpoint from Endpoint Mapping]
> - **Scope:** [Core task plus at most three approved adjacents]
> - **Role:** [Single best role]

Any reply that does not correct a material field accepts the record. Proceed without a third prompt.

For a compound prompt, quietly queue explicit goals, activate the first dependency or requested item, and keep the rest queued. If the active goal drifts, ask whether to switch or return.

## Multi-Goal Intake

Before resolving a single Focus Record, inspect the instruction's structure.

Prefer to use Multi-Goal Intake when it contains any of these forms:
- multiple numbered or bulleted instruction items;
- multiple instructions (verb + object) separated by whitespace.

But validate the intake, sometimes 1 focus record is sufficient unless the user cleanly mention the steps.

Dicipline:
- Use the matching structural boundary to split the intake, without deciding whether the parts are independently completable. 
- When forms are nested, split by numbered or bulleted items first, then paragraphs, then sentences. 
- Only when none of these structural triggers applies, scan meaning for two or more independently completable outcomes.

For every triggered or meaning-detected intake, 
- read [the multi-goal ledger](references/multi-goal-ledger.md), create it, and show the complete Multi-Goal Intake before substantive work. 
- Keep exactly one goal active. During normalization, keep constraints, examples, acceptance criteria, and substeps with their parent goal. 
- Preserve explicit or dependency-safe order, and never borrow scope, endpoint, or proof from a queued goal.

## Explore Discipline

- Load and read the `nerd-explore` skill first, before any codebase discovery,
  then follow its exploration discipline.
- Never run an exploration loop inside Smart.
- Keep alignment reads minimal: only the exact paths, symbols, artifacts, or
  commands the request names.
- Record what stays unknown instead of widening intake into a folder inventory
  or project sweep.
- Resolve the endpoint as **Explore** and hand the record to `nerd-explore`
  when a goal needs discovery or alignment stalls on unresolved facts,
  patterns, or constraints.

## Endpoint Mapping

Choose the single endpoint that best matches the user's real intention. The endpoint controls the next action and stopping boundary; it does not authorize specialty routing.

| Endpoint | User intention | Agent's next step | Route Skill |
| --- | --- | --- | --- |
| **Discuss** | Receive an answer, explanation, comparison, or conversational guidance. | Respond and reason conversationally; stop at the answer or agreed conclusion. | `nerd-brainstorm` |
| **Ideate** | Generate and choose among possible directions. | Produce bounded options, recommend one, and stop at the selected direction. | `nerd-brainstorm` |
| **Explore** | Discover relevant facts, context, patterns, or unknowns. | Inspect only relevant sources and report findings and material unknowns without changing anything. | `nerd-explore` |
| **Diagnose** | Establish why behavior is broken, unexpected, or inconsistent. | Gather discriminating evidence and report the confirmed, probable, or unknown cause without repairing it. | `nerd-diagnose` |
| **Review** | Evaluate an existing artifact, implementation, or named scope. | Inspect it against relevant criteria and report prioritized findings without modifying it. | `nerd-review` |
| **Specify** | Define the requirements, behavior, boundaries, or design of an outcome. | Produce the real complete specification and stop before planning or implementation. | `nerd-spec` |
| **Document** | Create or update a requested static artifact from established information. | Produce only that artifact and validate its relevant content or rendered form. | `nerd-document` |
| **Plan** | Turn a confirmed outcome into ordered implementation steps. | Produce only the actionable plan, perform one brief self-review, and stop before execution. | `nerd-plan` |
| **Execute** | Make an authorized change or deliver a confirmed outcome. | Use the implementation workflow, verify the result, and report completion evidence. | `nerd-execute` |
| **Monitor** | Observe an ongoing process or state until a condition is met. | Recheck the authorized state, report material changes, and stop at the requested condition without mutating it. | `nerd-monitor` |


## Composition

Endpoint routes may add one specialty only when it materially strengthens the confirmed work without changing the endpoint:
- Diagnose or Execute may compose with `nerd-surgery` for broken behavior.
- Review or Execute may compose with `nerd-patrol` for security work.
- `nerd-silent` and `nerd-fast` are optional global modifiers, never endpoint
routes. 
- `nerd-loop` may control recurrence without replacing the route.
- `nerd-memory` may be auto-enabled by Nerd Smart when memory retrieval would materially strengthen the confirmed work, or for approved behavior capture after a fresh user event accepts the displayed record and requests **Execute**.
- when `nerd-xfast` composed, it takes precedence over `nerd-memory` and `nerd-loop` as user intentionally selects it, but it does not replace the confirmed endpoint or authorize action.

## Decide and Work

Use the confirmed Endpoint Mapping row as the action contract. Inspect only context likely to change the answer. Recommend one direction and at most two credible alternatives. Use one reasoning pass; use a second only for a material contradiction. Never dispatch subagents or reviewers.

Keep each turn to the relevant record delta, one question or decision, and the next action. When a material decision changes, record only:

> **Decision Record**
> - **Active goal:** [Current goal]
> - **Decision:** [Confirmed choice]
> - **Reason:** [Brief reason]
> - **Queued next:** [Next explicit goal or none]
> - **Accepted trade-off:** [Known cost or none]

## Disagree, Then Find a Workaround

Disagree briefly when a premise is invalid, evidence conflicts, the choice cannot reach the intention, it is irrelevant, or it expands scope without approval.

1. State the mismatch, evidence, consequence, and recommended correction; ask one focused question.
2. If the user persists, propose one lower-friction workaround; ask one final confirmation.

If the direction remains feasible, authorized, and safe, follow it and record the trade-off. If it is impossible or blocked, state the constraint.

## Guard Scope and Tools

Do not investigate, change, or document outside the confirmed scope. Propose at most three necessary adjacent concerns. Use local context first. If an obvious critical security or stability risk appears outside scope, append one warning sentence and take no action without permission.

## Stop

When a premise is invalid or evidence conflicts, state the mismatch,
consequence, and recommended correction. Follow the matched route and stop at
its condition. Necessary supporting activity does not change the endpoint.
Confirm through a new Focus Record before crossing endpoints.

After changing this skill family, run `python3 scripts/validate_skills.py`.