/project

description: "Manage projects inside a topic wiki. Projects are folders under output/projects/ that group related outputs (playbooks, images, code, data) with a goal captured in WHY.md."
argument-hint: "new <slug> \"goal\" | list [--archived] | show <slug> | add <slug> <path> | archive <slug> [--include-archived]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(ls:*), Bash(mkdir:*), Bash(mv:*), Bash(date:*), Bash(basename:*), Bash(find:*), Bash(wc:*)

Your task

Manage projects — folders inside a topic wiki's `output/projects/` directory that group related outputs. The only required file in a project is `WHY.md`, which captures the goal/rationale in plain markdown.

**Resolve the wiki.** Do NOT search the filesystem or read reference files — follow these steps: 1. Read `$HOME/.config/llm-wiki/config.json`. If it has `hub_path`, expand leading `~` only (not tildes in `com~apple~CloudDocs`) and prefer that path; use `resolved_path` only as a fallback cache when the expanded `hub_path` is unavailable and `resolved_path` is initialized. If config has only `resolved_path`, use it. If the configured path can be statted but reading `wikis.json` or listing `topics/` fails with `Operation not permitted`, stop and ask the user to grant Full Disk Access/iCloud Drive access to the launcher; do not fall back to `~/wiki` or `resolved_path`. Do not write machine-specific `resolved_path` into shared configs. 2. If no config → read `$HOME/wiki/_index.md`. If it exists → HUB = `$HOME/wiki`. If nothing found, ask the user where to create the wiki. 3. **Wiki location** (first match): `--local` → `.wiki/` in CWD; `--wiki <name>` → `HUB/wikis.json` lookup with portable path resolution (`<HUB>`, `~`, absolute, or HUB-relative); if the registry path is stale, fall back to `HUB/topics/<name>`; CWD has `.wiki/` → use it; else → HUB. 4. Read `<wiki>/_index.md` if found. Variant: **wiki-neutral** — see deviation below for the step-4 fallback.

Archive rule: topic archive and project archive are different layers. Project commands operate on active topic wikis by default. If `--wiki <name>` resolves to a topic under `topics/.archive/`, stop and ask the user to restore the topic or rerun with `--include-archived`; explicit archived operations must stay inside that archived topic path. The project subcommand `archive <slug>` only moves `output/projects/<slug>` inside the selected topic wiki.

Read the projects architecture at `skills/wiki-manager/references/projects.md` for the full rationale — particularly *why* `WHY.md` is the only required file (it holds the precious, non-derivable rationale) and *why* everything else is derived from filesystem state.

Idea awareness: if the user says "turn this Idea into a Project," "approve the brief," or equivalent, route to the Idea promotion workflow in `skills/wiki-manager/references/ideas.md`. Promotion freezes `BRIEF.md` and cross-links the records. Keep `project new` available for direct Projects that do not originate as Ideas.

Inventory awareness: projects group outputs around a goal; inventory tracks durable items with status, priority, and next action. If the user asks for a project backlog, source queue, watch list, or task list, suggest inventory records or a saved inventory view linked from the project instead of putting tracking state directly in `WHY.md`.

Deviation: wiki resolution step 4

The standard prelude's step 4 (fallback to HUB) becomes: **ask the user which topic wiki, or fail if no topic wikis exist.** Project operations against an empty hub have nothing to operate on. All project paths below are relative to the resolved wiki root (`<wiki-root>/output/projects/<slug>/`).

Parse $ARGUMENTS

The first word is the subcommand. Subsequent words are args.

| Subcommand | Args | Purpose | |------------|------|---------| | `new` | `<slug> "goal"` | Create a new project with a WHY.md | | `list` | `[--archived]` | List projects (active by default) | | `show` | `<slug>` | Show a project's WHY.md and member files | | `add` | `<slug> <path>` | Move an existing file into a project | | `archive` | `<slug>` | Move folder to `.archive/` (reversible via mv) |

If `$ARGUMENTS` is empty, show help (list subcommands with examples) and exit.

Flag:

• **--include-archived**: Explicitly allow the selected topic wiki itself to be

archived. This is separate from `list --archived`, which includes archived projects inside an active topic wiki.

**Removed in v0.2 simplification**: `focus`, `unfocus`, `retract`, `rename`. See `references/projects.md` § "Focus" for the rationale on dropping focus (pass `--project <slug>` explicitly instead). Rename and retract are rare and better done via direct filesystem ops (`mv`, `rm -rf`) than wrapped subcommands.

---

Subcommand: `new <slug> "goal"`

Create a new project.

**Validate slug**:

• Lowercase only
• Hyphen-separated
• Max 40 characters
• No spaces, no uppercase, no special chars except `-`
• If invalid, suggest a corrected version and exit: `Invalid slug "Foo Bar" — use "foo-bar" instead.`

**Validate goal**: Mandatory. If missing, prompt: `Goal is required. What is this project trying to accomplish?`

**Check collision**: If `<wiki-root>/output/projects/<slug>/` already exists (active or archived), fail: `Project "<slug>" already exists at <path>. Use a different slug.`

**Create**: 1. `mkdir -p <wiki-root>/output/projects/<slug>/` 2. Write `<wiki-root>/output/projects/<slug>/WHY.md` using the template below 3. Report: `Created project "<slug>" at <path>.`

**`WHY.md` template**:

# <Title>

<goal>

## Context

<!-- Why this project exists, what triggered it, who cares. Delete this section if you don't need it. -->

## Current state

<!-- Where things stand, what's next, outstanding questions. Delete this section if you don't need it. -->

Derive the title from the slug: `bitcoin-quantum-risk` → `Bitcoin Quantum Risk`. Capitalize each hyphen-separated token. Drop the `<!-- ... -->` placeh