knowns-dev/knowns/kn-init

Session Initialization

Announce: "Using kn-init to initialize session."

Core principle: BOOTSTRAP WITH MCP INITIAL → DISCOVER WITH HELP → READ ONLY RELEVANT DOCS.

Inputs

• Optional user focus such as a task ID, feature area, bug, or question
• Current project root already opened in the agent session

Preflight

• Confirm this is a Knowns project
• Call MCP initial first when available; it is the runtime bootstrap
• Use help("tool.*") or help("workflow.*") when an action schema or workflow route is not visible
• Prefer project docs over guessing from code structure
• If README, ARCHITECTURE, or CONVENTIONS do not exist, choose the closest equivalents from the docs list
• If a doc is large, read its TOC first and only open the relevant sections

Step 1: Runtime Bootstrap

mcp_knowns_initial({})

If the MCP client exposes the tool as initial rather than mcp_knowns_initial, call that tool. Summarize project state, tool domains, active timer, and any warnings.

Step 2: List Docs

mcp_knowns_docs({ "action": "list" })

Step 3: Read Core Docs

mcp_knowns_docs({ "action": "get", "path": "README", "smart": true })

For large docs, do not read the whole file. Use:

mcp_knowns_docs({ "action": "get", "path": "<path>", "toc": true })
mcp_knowns_docs({ "action": "get", "path": "<path>", "section": "<heading-or-number>" })

Step 4: Check Current State

mcp_knowns_tasks({ "action": "list", "status": "in-progress" })
mcp_knowns_tasks({ "action": "board" })

Note the shape of the Task IDs you get back. New IDs always carry a prefix, from settings.defaultTaskIdPrefix or, when that is unset, derived from the project name, so they look like KN-4F7Q2M. Older tasks may still have plain IDs like 4f7q2m. Either way, pass the ID exactly as printed: the hyphen in KN-4F7Q2M is part of the ID, not a task- reference prefix to strip.

The initial tool reports the active format. Over MCP you can override the prefix per Task with tasks({ action: "create", prefix: "SPC" }); changing the project default is a CLI or Settings action, not an MCP one:

knowns config get settings.defaultTaskIdPrefix --plain   # empty = derived from project name
knowns config set settings.defaultTaskIdPrefix SPC

Step 4.5: Load Critical Learnings

Check for accumulated critical learnings from past work:

mcp_knowns_search({ "action": "search", "query": "critical patterns", "type": "doc", "tag": "critical" })

If learnings/critical-patterns exists:

mcp_knowns_docs({ "action": "get", "path": "learnings/critical-patterns", "smart": true })

These are promoted learnings that cost the most to discover and save the most by knowing. Include a brief summary in the session context if any exist.

Step 4.6: Load Project Memory

mcp_knowns_memory({ "action": "list", "layer": "project" })

Project memories contain accumulated patterns, conventions, preferences, and failures from past work. Include only entries relevant to the user's focus; do not serialize the entire memory list. Retrieve relevant accepted/current first-class System Decisions separately; Memory category decision is legacy and must not be used for new capture.

Step 4: Summarize

## Session Context
-**Project**: [name]
-**Key Docs**: README, ARCHITECTURE, CONVENTIONS
-**Critical Learnings**: [count, or "none yet"]
-**Project Memories**: [count, or "none yet"]
-**In-progress tasks**: [count]
-**Current risks / gaps**: [missing docs, unclear conventions, broken search, etc.]
-**Ready for**: tasks, docs, questions

Final Response Contract

All built-in skills in scope must end with the same user-facing information order: kn-init, kn-spec, kn-flow, kn-go, kn-plan, kn-research, kn-handoff, kn-implement, kn-test, kn-review, kn-debug, kn-decision, kn-verify, kn-doc, kn-template, kn-extract, and kn-commit.

Required order for the final user-facing response:

1. Goal/result - state what session context was established or what was confirmed.
2. Key details - include only the most important supporting context, refs, risks, or current-state notes.
3. Next action - recommend a concrete follow-up command only when a natural handoff exists.

Keep this concise for CLI use. Skill-specific content may extend the key-details section, but must not replace or reorder the shared structure.

Do not manage platform-synced skill copies; this source defines the built-in workflow contract.

For kn-init, the key details should cover:

• 1 short paragraph or bullet list summarizing project purpose and architecture
• 1 short list of the most relevant docs opened
• current in-progress work, if any
• current risks or missing context, if any

Fallbacks

• If task search/list is unavailable, state that clearly and continue with docs + codebase context
• If core docs are missing, say which docs were not found and which substitutes were used
• If initial is unavailable, fall back to project({ action: "status" }) and targeted docs
• Do not invent project conventions that were not found in docs or code

When a follow-up is natural, recommend exactly one next command such as:

/kn-plan <task-id>
/kn-flow @doc/<approved-spec-path>
/kn-research <query>
/kn-handoff