alive-create-walnut

name	alive:create-walnut
version	3.0.0
description	Something new is emerging. A venture, an experiment, a person entering the orbit, a life area getting serious. It needs its own walnut — its own identity, history, and future. Scaffolds the full structure, maps existing context sources, and optionally migrates files across.
user-invocable	true

Create

Scaffold a new walnut — any type, any ALIVE domain. Understand it first, map where its context lives, then scaffold. Optionally bring in existing content (Step 7 — only if the human has files to migrate).

Not a setup wizard (that's world/setup.md — first-time only). Not opening an existing walnut (that's alive:load-context).

---

Template Locations

The squirrel MUST read these templates before writing — not reconstruct from memory. Templates live relative to the plugin install path.

templates/walnut/key.md            → _kernel/key.md
templates/walnut/key-codebase.md   → _kernel/key.md (codebase variant, Step 2b)
templates/walnut/log.md            → _kernel/log.md
templates/walnut/insights.md       → _kernel/insights.md

Placeholders

Used in key.md and key-codebase.md:

Placeholder	Source
{{type}}	Step 1 selection
{{goal}}	Extracted from Step 2 free text
{{name}}	Kebab-case slug derived from Step 2
{{date}}	Current ISO date (YYYY-MM-DD)
{{description}}	The human's free text from Step 2, lightly cleaned

Additional placeholders in key-codebase.md (Step 2b only):

Placeholder	Source
{{repo}}	Repository URL from Step 2b
{{local_path}}	Local clone path from Step 2b
{{github_account}}	GitHub account or org from Step 2b
{{stack}}	Tech stack summary from Step 2b
{{branch}}	Default branch name from Step 2b

Used in entry.yaml (squirrel — written by session-new hook, not by this skill):

Placeholder	Source
{{session_id}}	Current session ID
{{engine}}	Current model (e.g. claude-opus-4-6)
{{walnut}}	Same as {{name}}
{{squirrel_name}}	From preferences.yaml squirrel_name: or null
{{timestamp}}	ISO timestamp at session start
{{transcript}}	Path to session transcript JSONL
{{cwd}}	Working directory at session start
{{rules_loaded}}	Count of rules loaded at session start

---

Domain Routing

Type	ALIVE folder	Notes
venture	04_Ventures/{name}/
experiment	05_Experiments/{name}/
life	02_Life/{name}/	Under goals/ if it's a goal
person	02_Life/people/{name}/	Legacy subfolder conventions (professional/, inner/, orbit/) still recognized.
project	Inside parent walnut folder	Requires parent selection
campaign	Inside parent walnut folder	Requires parent selection

---

Flow

Step 1 — Type Selection

-> AskUserQuestion: "What type of walnut?"
- Venture — revenue intent (business, client, product)
- Experiment — testing ground (idea, prototype, exploration)
- Life area — personal (goal, habit, health, identity)
- Person — someone who matters
- Project — scoped work inside a venture or experiment
- Campaign — time-bound push with a deadline

Step 2 — Describe It

Free text prompt: "Describe it in a sentence or two — what is it and what's the goal?"

The squirrel infers name (kebab-case slug), goal, and domain from the response.

If type is project or campaign:

-> AskUserQuestion: "Which walnut does this belong under?"
- [list active ventures/experiments by scanning _kernel/key.md frontmatter across ALIVE folders]
- Standalone (no parent)

To build the parent list: scan 04_Ventures/*/_kernel/key.md and 05_Experiments/*/_kernel/key.md — read frontmatter only (type, goal). Check _kernel/key.md first, fall back to walnut root. Present as options with goal as description.

Step 2b — Codebase Detection

Skip Step 2b entirely for type: person or type: life walnuts — they don't have codebases.

For venture, experiment, project, or campaign walnuts: if the description mentions code, a repo, a website, an app, or anything that lives in a git repository:

╭─ 🐿️ sounds like this has a codebase. That right?
│
│  ▸ Does this walnut track a code repo?
│  1. Yes
│  2. No — context only
╰─

If yes, ASK explicitly for each required field — do not infer from the description:

╭─ 🐿️ codebase details
│
│  ▸ What's the repo? (e.g., github.com/org/repo)
│  ▸ Where's it cloned locally? (e.g., ~/code/my-project)
│  ▸ Any of these apply?
│    - GitHub account (if you use multiple)
│    - Deploy platform (Vercel, Netlify, etc.)
│    - Database (Supabase, Postgres, etc.)
╰─

Even if the human gave repo/path in their description, confirm them here. This step is the only place codebase info is collected — don't skip it.

Set has_codebase: true — Step 6 will use templates/walnut/key-codebase.md instead of the standard template.

Step 3 — Pull the Thread

Five minutes of conversation here saves ten sessions of backfilling. Don't rush past this.

Ask follow-ups adapted to the type. Use natural conversation, not an interrogation — if they gave a rich answer in Step 2, skip questions you can already infer.

Type	Ask about
Venture	Who's involved — names, roles, how you work with them? What's the business model or revenue path? What phase — idea, building, launched? Any hard deadlines or external commitments?
Experiment	What exactly are you testing? Who else is involved? What would make you kill it vs double down?
Person	How do you know them? What do you work on together? How do you usually communicate?
Life area	Why now? What does progress look like? Who else is involved or affected?
Project / Campaign	Who's on it? What's the deadline? What does done look like?

From the answers, extract and hold for scaffolding:

• People — names, roles, contact info if offered -> _kernel/key.md people: frontmatter + ## Key People
• Phase — starting, planning, building, testing, launched -> _kernel/now.json phase:
• Rhythm — how often they'll touch this (override weekly default if appropriate)
• Tags — inferred from domain, industry, tools, people mentioned
• Description — 2-3 sentence identity paragraph -> _kernel/key.md body

Step 4 — Context Map

Most new walnuts already have context scattered across tools. Map it now so the squirrel knows where to look later.

╭─ 🐿️ context map
│  Where does context for this currently live outside
│  your head? Knowing this helps me find things later
│  and reminds the human what to bring in.
│
│  Think about:
│  - Email threads (Gmail, Outlook)
│  - Chat history (Slack, WhatsApp, iMessage, Discord)
│  - Documents (Google Drive, Notion, Dropbox)
│  - Meeting recordings (Otter, Fathom, Zoom recordings)
│  - Notes (Apple Notes, Obsidian, paper notebook)
│  - Code or repos (GitHub, local projects)
│  - Social / public (Twitter, LinkedIn, website)
│  - Anything else — spreadsheets, Figma, Trello, etc.
╰─

-> AskUserQuestion (multiSelect): "Email (Gmail/Outlook)" / "Chat (Slack/WhatsApp/Discord)" / "Docs (Drive/Notion/Dropbox)" / "Other (tell me)"

Follow up briefly on each selected source — which channels, which folders, key threads. Not exhaustive, just enough to know where shadow context lives.

This becomes a ## Context Map section in _kernel/key.md:

## Context Map

| Source | Details | Status |
|--------|---------|--------|
| Gmail | Thread with [e-mail] re: shielding specs | Not captured |
| Slack | #nova-engineering channel | Ongoing |
| Google Drive | "Nova Station" shared folder | Not captured |
| Fathom | 3 recorded calls with engineering team | Not captured |

Status: Not captured - Partially captured - Ongoing (live channels) - Captured

This map is a living reminder. When the squirrel opens this walnut later, it can prompt: "Your context map shows 3 Fathom recordings marked 'Not captured' — want to bring those in?"

Step 5 — Confirm Before Writing

Present everything gathered so far:

╭─ 🐿️ new walnut
│
│  Name:    flux-engine
│  Type:    experiment
│  Goal:    Build a propulsion flux simulator for orbital testing
│  Path:    05_Experiments/flux-engine/
│  Parent:  none
│  Rhythm:  weekly (default)
│  People:  2 (Jax Stellara, Dr. Elara Voss)
│  Repo:    github.com/org/flux-engine -> ~/code/flux-engine  (if codebase)
│  Context: 4 sources mapped (Gmail, Slack, Drive, Fathom)
│
│  ▸ create / change name / change type / change rhythm / cancel
╰─

If the human picks "change name" / "change type" / "change rhythm", ask once, then re-present the confirmation.

Step 6 — Scaffold

Structure is flat: everything lives directly in _kernel/. No _generated/ subdirectory. No bundles/ directory at creation time — bundles are created on demand by alive:bundle.

1. Domain already determined (Step 1-2 above)
2. Create folder at the resolved path (kebab-case name)
3. Create _kernel/ directory (flat — NO _generated/ subdirectory)
4. Read each template from templates/walnut/, fill {{placeholders}}, write to _kernel/ inside the walnut. If has_codebase: true, use templates/walnut/key-codebase.md instead of templates/walnut/key.md — fill the dev: block with repo, local_path, and any optional fields collected in Step 2b
5. Fill _kernel/key.md frontmatter: type, goal, created (today), rhythm, people (from Step 3), tags (from Step 3)
6. Fill _kernel/key.md body: description from Step 3, ## Key People with roles, ## Context Map from Step 4, ## Connections with any wikilinks to existing walnuts
7. Write first log entry: "Walnut created. {goal}" — signed with session_id
8. Create _kernel/tasks.json with contents: {"tasks": []}
9. Create _kernel/completed.json with contents: {"completed": []}
10. Generate _kernel/now.json — run project.py --walnut {path} (located at scripts/project.py relative to plugin install). If project.py is unavailable or fails, write a minimal now.json manually:

    {
      "phase": "starting",
      "updated": "YYYY-MM-DDTHH:MM:SSZ",
      "squirrel": null,
      "bundles": {"active": {}, "recent": {}, "summary": {"total": 0, "done": 0, "draft": 0, "prototype": 0, "published": 0}},
      "unscoped_tasks": {"urgent": [], "active": [], "todo": [], "counts": {"urgent": 0, "active": 0, "todo": 0, "blocked": 0}},
      "recent_sessions": [],
      "children": {},
      "blockers": [],
      "context": ""
    }
    

11. If sub-walnut: set parent: [[parent-name]] in _kernel/key.md frontmatter
12. Add [[new-walnut-name]] to parent's _kernel/key.md links: frontmatter field
13. Update .alive/key.md — route by type:
    • type: person → append to ## Key People: - [[new-walnut-name]] — {role}
    • All other types → append to ## Connections: - [[new-walnut-name]] — {goal} Use em-dash (—), not double hyphen (--). If .alive/_index.yaml exists, regenerate it too.

╭─ 🐿️ scaffolding...
│
│  > 05_Experiments/flux-engine/
│  >   _kernel/key.md — type: experiment, goal set, 2 people, 4 context sources
│  >   _kernel/log.md — first entry signed
│  >   _kernel/insights.md — empty, ready
│  >   _kernel/tasks.json — empty task list
│  >   _kernel/completed.json — empty completed list
│  >   _kernel/now.json — phase: starting
│
│  Walnut is alive.
╰─

Step 7 — Existing Content Check

DO NOT read create/migrate.md until the human answers "yes" below. It is a large file that must not be loaded into context unless needed. Most walnut creations will skip this step entirely.

╭─ 🐿️ got files to bring in?
│
│  If you have docs, notes, or a project folder on your
│  computer for this — I can pull them in now.
│
│  Tip: if you've got a bunch of scattered files, throw
│  them all into one folder first and point me at it.
│  I'll work through each one — manifests, frontmatter,
│  the lot.
╰─

-> AskUserQuestion: "Yes — I have files to bring across" / "No — starting fresh"

If "No" — done. Offer: "Say open {name} to start working."

If "Yes" — NOW read create/migrate.md and follow it from the Entry Point section. The migrate skill handles everything from here: asking what kind of content, detecting whether it's a light seed or full project migration, and running the appropriate flow.

---

---

Bundle Creation

Bundle scaffolding is handled by alive:bundle. When the human says "create a bundle" or when stash routing identifies a new body of work, invoke the bundle skill — it handles the full create flow including manifest template, raw/ directory, and now.json update.

Do NOT create a bundles/ directory during walnut scaffolding. Bundles are created on demand by the bundle skill, which handles directory creation itself.

---

Bundle -> Walnut Graduation

When a bundle grows too big for its container (needs its own sessions, log, lifecycle):

1. Confirm with the human: "This bundle wants to be a walnut. Graduate it?"
2. Determine ALIVE domain and name
3. Scaffold new walnut (Step 6 above)
4. Seed _kernel/key.md from bundle manifest (goal, tags, people carry over)
5. Move bundle contents into the new walnut as its first bundle (bundle skill handles directory creation)
6. Log entry in BOTH parent walnut ("Bundle {name} graduated to walnut") and new walnut ("Graduated from {parent}")
7. Add wikilink [[new-walnut]] to parent's _kernel/key.md links:

---

Files Created

File	Template source
{domain}/{name}/_kernel/key.md	templates/walnut/key.md (or key-codebase.md)
{domain}/{name}/_kernel/log.md	templates/walnut/log.md
{domain}/{name}/_kernel/insights.md	templates/walnut/insights.md
{domain}/{name}/_kernel/tasks.json	Literal: {"tasks": []}
{domain}/{name}/_kernel/completed.json	Literal: {"completed": []}
{domain}/{name}/_kernel/now.json	scripts/project.py --walnut {path} (or minimal fallback)
Parent's _kernel/key.md	Updated links: field (if sub-walnut)

Files Read

File	Why
templates/walnut/key.md	Template — read before writing key.md
templates/walnut/key-codebase.md	Template — read before writing key.md (codebase variant)
templates/walnut/log.md	Template — read before writing log.md
templates/walnut/insights.md	Template — read before writing insights.md
templates/squirrel/entry.yaml	Schema for squirrel entry
rules/world.md	The walnut scaffolding process — follow exactly
Active walnuts' _kernel/key.md frontmatter	For parent list (project/campaign types only)