map

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Map

A map is work in its own right, with a scope and a result the user asked for. Learning while working - the default - needs none of this: the [record skill](../record/SKILL.md) keeps findings as they arise, and the first useful one creates the record. Run `kpop` or `kpopper` from the native runtime and prefer the canonical executable in `KPOPPER_AGENT_CONTEXT.command`. Do not guess a path or silently use PATH. An existing record is read only through kpopper; neither the mapping agent nor a delegated agent loads or searches its YAML directly.

In ordinary conversation, name the product **kpopper** and describe the action in the user's language. Reserve the exact skill name `kpopper:map` for invocation instructions, technical documentation, debugging, or explaining this specific skill. Fold the product name into the explanation of the action; no extra announcement is needed.

**If it does not exist:** there is no record here yet; knowledge may already live in the
materials. Run `kpop open` if the hook did not supply `KPOPPER_START`, and follow
`kpopper _agent guide` for the optional first offer, source discovery and contextual explanations.
An unavailable registered record is a location problem, not a new project.

## The starting offer, once

In a Git project, use the routing and Board information from `kpopper _agent guide`.
An unconfigured project already uses private central Simple; mapping is not a reason to ask
about storage mode. `kpop board` reports publication state separately. Advanced is available
only through the explicit Experimental command, and silence never counts as consent. A
read-only map must not bind a provisional central path or create a record. Preserve existing
records until a validated transition. Mapping and deeper investigation remain available
whenever requested.

For non-Git Simple projects where a workspace has no record and the work is clearly going to be revisited, offer the three
starting choices once, briefly, at the first suitable moment in real work: **learn while working**
(the default), **map existing materials**, or **investigate more deeply**. Allow skipping. Do not
interrupt urgent work, and do not ask on a greeting - a session that only said hello gets no
offer. No answer means continue the task, not permission to scan. After showing the offer run
`kpopper _agent shown welcome`; the choice and what was shown are remembered per project and per
user, so a later session does not repeat them, and `kpopper _agent status` says what is still
unseen. Skip the introductory explanation for a user who has already seen it in another project.
`kpop config --guidance off` turns explanations off without turning the work off.

**Mapping is available by choice.** Offer learning while working, an initial map of existing
materials, or a deeper investigation within agreed subjects, sources and dates. An explicit
mapping request already chooses that work; no extra confirmation is needed. Use the guide
to locate where decisions happen and to keep historical accounts separate from present
findings. Do not expand into unrelated private sources or infer permission from silence.
For an explicit mapping request, call `kpop map --json` or `kpop map --deep --json`
with the host session environment, accept and execute the returned task, and report its actual
result through the supplied internal protocol. Do not stop after announcing a ready task.
Learning during ordinary work needs no configuration. Public operations are `open`, `map`,
and `config --guidance on|off`; request IDs and receipt calls are internal.

**Teach through actual events.** A compact card can explain the first saved finding, linked
source, grounded decision, conflict, reuse, or changed premise. Show real links where available
and use the host's native card or a Markdown block. `kpopper _agent status` lists unseen concepts;
`kpopper _agent shown EVENT` acknowledges an explanation only after displaying it. The introduction
is remembered per user, the starting offer per project. Respect `kpop config --guidance off` and do
not turn an onboarding step into a requirement for finishing the user's task.

A selected mapping or investigation makes discovery the task: follow `kpopper _agent guide` (the packaged [start guide](../../native/shared/start-guide.md)), stay inside the agreed subjects, sources and dates, and report its limits. The availability of more material is not a reason to survey it. The result is a report the user can read and a record whose first entries carry their sources; render the optional experimental [hub](../hub/SKILL.md) only if explicitly requested or covered by a standing preference.

From ilanbm/kpopper, MIT.

More from ilanbm/kpopper