Orion/.agents/skills/orion-instantiate/SKILL.md

name

description

orion-instantiate

Create a Project (workstream) or Area in an Orion vault against its frontmatter contract. Runs the done-when test first, assigns the workstream ID from the Area's counter, seeds the Area's knowledge/ folder, and registers the new hub so it is never an orphan. Also converts a Project that turns out to be an Area. Triggers on: new project, new area, new workstream, create project, create area, instantiate, this should be an area.

orion-instantiate — create a Project or Area

Creation is where most structural defects start: a hub with no done-when never finishes, a hub with no Area can never be measured against anything, and a hub nobody links to is an orphan from day one. This skill makes creation follow the contract in 6. Templates/_contracts.md instead of copying a template and hoping.

---

1. The test — before anything else

Question	If yes
Can you write "this is done when ___" in one sentence, right now?	Project
Is the honest answer "it's never done"?	Area
Neither, but facts and people attach to it?	Resource or person page — not a hub. Stop here

⚠ If the done-when needs "ongoing", "maintain", or "as needed", it is not a Project. It is an Area, or a task inside one.

If the owner hasn't given a done-when and you can't derive one from what they said, ask for it. No done-when, no Project.

---

2. Creating an Area

1. Folder: 2. Areas/<Area Name>/ (Title Case, spaces).
2. Hub: <Area Name>_hub.md from 6. Templates/area-hub.md:
   • type: area, status: standing
   • id_prefix: — short, uppercase, unambiguous, not already used by another Area (grep every *_hub.md for id_prefix:). Permanent once set.
   • workstream_counter: 0
   • parent: only if nested, and never pointing at itself.
3. Seed knowledge/_index.md — the Area's permanent memory. State in two or three lines what belongs here (durable material that needs this Area's frame to make sense) and what doesn't (reusable-anywhere material → 3. Resources/Research/; process notes → the workstream). This is the step that gets skipped. Without an obvious home, knowledge scatters.
4. Pick an Area tag (lowercase-kebab) and register it in wiki/meta/tags.md.

3. Creating a Project (workstream)

1. Pick its Area. Default: every Project has one. If it genuinely has none, write area: none explicitly — absent is indistinguishable from an oversight. ⚠ An area: none Project has no counter to draw an ID from: use prefix X with the next number not used by any hub in 1. Projects/ or 5. Archive/, and tell the owner its deliverable will archive whole on close.

2. Assign the ID — read the counter, never scan for it.

   1. Read workstream_counter: on the Area hub.
   2. Increment it and write the new value back first.
   3. id: <PREFIX>-<new value>.

   ⚠ Scanning existing hubs for the highest ID collides. Closed projects have moved to 5. Archive/, so a scan of 1. Projects/ sees a lower maximum than was issued. The counter persists; the hubs don't. IDs are never reused.

3. Folder: 1. Projects/<Area>/<Project Name>/. Hub: <ID>_hub.md from 6. Templates/project-hub.md.

4. Frontmatter: type: project (never hub), id, area, done_when (the sentence verbatim, not a paraphrase), status: open, updated, tags: [hub, <area-tag>]. Add next: if a first move is known.

4. Register — part of creation, not after it

• Project: listed on its Area hub under ## Workstreams with its ID and status
• Project: Area's workstream_counter: incremented
• Area: tag in wiki/meta/tags.md; knowledge/_index.md seeded
• At least one inbound link (Area hub → Project; wiki/index.md → Area)
• Suggest cascade — structure changed

---

Converting a Project that turns out to be an Area

A Project that fails the done-when test isn't finished — it was misfiled. Ask the owner before converting; it is a change, not a repair.

1. Correct the hub first. Converting a hub with false statements relocates them.
2. Route everything in a table in the hub: each task or sub-effort → done (history) · ongoing (Area open item) · has a real done-when (its own new Project with an ID) · dead (closed, reason stated).
3. Move the folder to 2. Areas/<Name>/, rename the hub <Name>_hub.md, set type: area, status: standing.
4. ⚠ Give it id_prefix: and workstream_counter: 0 now. Conversion is the one path into Area-hood that skips the creation contract; an Area without a counter can never spawn a workstream, and nothing reports it.
5. Seed knowledge/_index.md. Repoint inbound links (see orion-close step 6 for method). Log it. Cascade.

---

Output

## Instantiate — <ID or Area name>

Done-when: "<sentence>"            (Projects)
Created: <path>
ID: <PREFIX>-<N> — counter now <N> (Projects)
Registered: <Area hub listing · tag · knowledge/ seeded · inbound link>

Next: run cascade.

Rules

• Done-when test first. No sentence, no Project.
• type: is project or area. Never hub.
• Read the counter, write it back, then use it. Never derive IDs by scanning. Never reuse one.
• area: none is legal but written. Absent ≠ none.
• Every Area gets id_prefix, workstream_counter and knowledge/ however it came into being.
• Register on creation. An unregistered hub is an orphan.