new-project

name	new-project
description	Scaffolds a new Second Brain project folder via interview. Interviews the owner on name, type, tier, intent, done-criteria, and scaffold richness, then creates the canonical Second Brain project docs (ORIENTATION.md + UNOFFICIAL INTENT_SPEC.md + TODO_[Name].md) plus optional CLAUDE.md / BUILD_SPEC.md / COCKPIT.md / DESIGN.md / README.md depending on project type. Each project gets an INTENT_SPEC.md — a short vision doc you author at project start and refer back to — drafted UNOFFICIAL until you review and promote it. Use when user says "new project", "scaffold project", "start a project", "/new-project", "create a project folder", or asks to begin a competition/campaign/build/writing project that needs structured docs.
user_invocable	true
allowed_tools	["AskUserQuestion","Read","Write","Bash","Glob"]
required_context_files	["Orientation_Docs/INTELLECTUAL_LANDSCAPE.md"]

New Project

Scaffolds a fresh Second Brain project folder with canonical docs by interviewing the owner. The interview output becomes the first draft of the project's intent — marked UNOFFICIAL until the owner reviews and promotes it.

What an INTENT_SPEC is

The centerpiece doc this skill creates. An intent spec is a short document you author at the start of a project that holds the vision for what it should be — what it's for, its core non-negotiable principles, and what "done" looks like — and that you refer back to as the project evolves. It's drafted UNOFFICIAL (agent-drafted from your interview answers) and becomes OFFICIAL once you've read and ratified it. That's the whole paradigm — keep it that lightweight.

Step 0 — Silent Context Load

Before doing anything else, silently Read each file in required_context_files if it is not already in your context. Do NOT announce the reads. Do NOT ask permission.

Files:

• Orientation_Docs/INTELLECTUAL_LANDSCAPE.md — project tier definitions + existing roster

Trigger Conditions

• User says "new project", "scaffold project", "start a project", "/new-project", "create a project folder"
• User describes a new initiative (competition entry, product idea, build, research program) that needs a home before work begins

Philosophy

Owners converge on the same project structure by hand across many projects. This skill formalizes what already happens — it does not invent new conventions. Every file it produces follows a pattern already observed in the wild (e.g. a game project for INTENT_SPEC, a classifier project for CLAUDE.md, an evolver project for COCKPIT, a persona project for ORIENTATION).

Universal review gate. Every document this skill generates carries a Review status banner directly under the H1. The banner points at a central REVIEW_LOG.md at the project root that tracks every file's status in one table. See any owner-authored project with a REVIEW_LOG.md for a canonical reference.

Banner format:

> **Review status:** `STATUS` · last touched YYYY-MM-DD · tracker: `REVIEW_LOG.md`

7-state vocabulary (canonical scheme):

• SCAFFOLD — auto-generated by /new-project, never touched since
• DRAFT — Claude modified post-scaffold, not yet seen by the owner
• PRESENTED — shown to the owner inline in chat; may or may not have commented
• REVISED — PENDING REVIEW — the owner gave feedback, Claude integrated, the owner has NOT re-read. The trap state. Sticky until the owner explicitly approves.
• APPROVED — the owner explicitly said yes / seems fine / good / etc.
• VERBATIM — the owner's own dictation preserved exactly; no review concept applies
• LOCKED — APPROVED AND frozen; downstream docs can safely derive

Rules:

1. Agents update REVIEW_LOG.md AND the per-doc banner in the SAME turn as any doc edit. No silent changes.
2. Agents NEVER self-promote a doc to APPROVED. Only the owner does that.
3. REVISED — PENDING REVIEW is sticky — stays until the owner explicitly approves, even if the changes look correct.
4. Downstream specs can't be LOCKED until their upstream is APPROVED.
5. When a doc gets refactored, don't lose prior state — leave a one-line history in the Notes column.
6. Inline "note this" comments from the owner add a Notes entry; they do NOT change status.

INTENT_SPEC exception: INTENT_SPEC.md uses its own UNOFFICIAL - PENDING OWNER REVIEW / OFFICIAL header instead of the Review status banner — the UNOFFICIAL/OFFICIAL marker serves the same purpose. It is still tracked in REVIEW_LOG.md the same as every other doc.

Intent specs are owner-authored. This skill produces UNOFFICIAL drafts from an interview — the owner promotes them to OFFICIAL by removing the UNOFFICIAL header after their own review. The skill does not auto-update INTELLECTUAL_LANDSCAPE.md or STATE_OF_SECOND_BRAIN.md; those are owner-authored and the skill leaves a reminder instead.

Workflow

Step 1 — Interview Round A (identity)

Use AskUserQuestion to collect these four fields in one call:

1. Project name — folder-safe. If the user gives a name with spaces, normalize to Name_With_Underscores. Ask as free text. (__FILL_FROM_USER__:project_name)
2. Project type — one of: campaign / software / writing / research / physical-build / fiction / superpower
3. Tier — 1 (active, shipping) / 2 (ongoing) / 3 (high priority inactive) / 4 (on roster) / 5 (parked)
4. Scaffold richness — minimal (3 docs) / rich (adds type-appropriate extras)

Project-type → extra-docs mapping (applies only if rich is chosen):

Type	Adds
campaign	CLAUDE.md, DESIGN.md, BUILD_SPEC.md
software	CLAUDE.md, BUILD_SPEC.md, README.md
writing	CLAUDE.md, DESIGN.md
research	CLAUDE.md
physical-build	CLAUDE.md, BUILD_SPEC.md, DESIGN.md
fiction	DESIGN.md
superpower	CLAUDE.md, COCKPIT.md, BUILD_SPEC.md

Step 2 — Interview Round B (intent)

Use AskUserQuestion (or free-text prompt if the answer needs to be long) to collect:

1. What is this for? — one-paragraph intent, in the owner's own words. Do not paraphrase. This becomes the "What This Is For" section of INTENT_SPEC.md.
2. Core intent bullets — non-negotiable principles, ~3–7 bullets. The owner's voice, declarative, no hedging.
3. Done criteria — what does "shipped" look like? One or two sentences.
4. Related projects — free-text list of existing Second Brain projects or files this connects to. Written into ORIENTATION.md's Connections section.

If the owner gives partial answers or says "you draft it," the skill may draft initial content — but the UNOFFICIAL marker stays until the owner reviews.

Step 3 — Confirm before writing

Present a summary of what the skill will create:

About to create: Projects/[Name]/
  ORIENTATION.md
  INTENT_SPEC.md (UNOFFICIAL)
  TODO_[Name].md
  [+ CLAUDE.md / DESIGN.md / BUILD_SPEC.md / COCKPIT.md / README.md as applicable]

Type: [type]
Tier: [tier]
Intent draft (first sentence): "[first sentence]"

Proceed? Y/N

Wait for explicit Y before writing files.

Step 4 — Check for collision

Before writing, run ls Projects/[Name]/ via Bash. If the folder exists and has any files, STOP and report — never overwrite an existing project.

Step 5 — Write the scaffold

Always create:

• Projects/[Name]/ directory
• ORIENTATION.md
• INTENT_SPEC.md (with UNOFFICIAL header)
• TODO_[Name].md

Conditionally create based on type + rich flag (see mapping above).

Canonical file templates:

Every template except INTENT_SPEC leads with the general UNREVIEWED banner below. INTENT_SPEC uses its own UNOFFICIAL header (shown further down) instead — the UNOFFICIAL/OFFICIAL marker is its review gate.

Universal UNREVIEWED banner (top of every generated doc except INTENT_SPEC)

> **Review status:** `SCAFFOLD` · last touched [YYYY-MM-DD] · tracker: `REVIEW_LOG.md`

ORIENTATION.md

> **Review status:** `SCAFFOLD` · last touched [YYYY-MM-DD] · tracker: `REVIEW_LOG.md`

# [Project Name]

## What This Is

[One paragraph, owner-voiced, based on interview answer to "What is this for?"]

## Structure

- **[Subfolder/]** — [purpose] (if applicable)
- **[CanonicalDoc.md]** — [what lives here]

## Status

Tier [N] — [active / ongoing / inactive / on roster / parked]
Created: [YYYY-MM-DD]
Last activity: [YYYY-MM-DD]

## Connections

- [Related project or file path] — [one-line relationship]

INTENT_SPEC.md

> **Status:** UNOFFICIAL - PENDING OWNER REVIEW. Drafted by /new-project on [YYYY-MM-DD] from an interview with the owner. This is the project's vision doc — what it's for, its core principles, and what done looks like. Promote to OFFICIAL by removing this header once the owner has reviewed and (where needed) rewritten the content below.

# [Project Name] — Intent

## What This Is For

[Interview answer, verbatim where possible]

## Core Intent

- **[Principle 1]** [Supporting sentence]
- **[Principle 2]** [Supporting sentence]
- [...]

## Done Criteria

[Interview answer]

## What This Is Not

[To be filled by the owner during review — scaffold leaves prompting comment]

## Already Settled (Not Open Questions)

[To be filled by the owner during review]

## Not Declared Here (Lives Elsewhere)

[If BUILD_SPEC.md is also being created, note: "Operational detail (tech stack, architecture, pipeline) lives in BUILD_SPEC.md."]

TODO_[Name].md

> **Review status:** `SCAFFOLD` · last touched [YYYY-MM-DD] · tracker: `REVIEW_LOG.md`

# TODO — [Project Name]

*Created: [YYYY-MM-DD]*

## Now

- [ ] Review UNOFFICIAL INTENT_SPEC.md, promote to OFFICIAL
- [ ] Add to STATE_OF_SECOND_BRAIN.md Tier [N] table (if Tier 1–3)

## Next

[Seeded from interview context — skill proposes 2–4 items; owner edits]

## Later

[Empty; grows over time]

## Done

[Empty; items move here as completed]

CLAUDE.md

> **Review status:** `SCAFFOLD` · last touched [YYYY-MM-DD] · tracker: `REVIEW_LOG.md`

# [Project Name] — Claude Instructions

## Read First

Read `ORIENTATION.md` and `INTENT_SPEC.md` before any substantive work on this project.

## Hard Rules

### Review-Gate Rule (Universal)

Every document in this project that an agent creates or edits carries an `UNREVIEWED` banner at the very top. The banner stays until the owner reads the document and removes it. If an agent edits the document again later — even a small edit, even to incorporate the owner's feedback — the banner returns. Approval is granted by the owner reading, not by silence and not by the owner giving verbal feedback. Tooling and downstream agents may treat any doc carrying `UNREVIEWED` as provisional and refuse to rely on it for load-bearing decisions.

[Project-specific rules — skill seeds from interview + type defaults; owner refines]

## Structure

| What | Where |
|------|-------|
| Intent | `INTENT_SPEC.md` |
| Orientation | `ORIENTATION.md` |
| Tasks | `TODO_[Name].md` |
| [Other] | [Other] |

DESIGN.md

> **Review status:** `SCAFFOLD` · last touched [YYYY-MM-DD] · tracker: `REVIEW_LOG.md`

# [Project Name] — Design

## Aesthetic Direction

[Type-appropriate prompt; owner fills]

## Palette / Typography / Motion

[Empty; grows as decisions are made]

BUILD_SPEC.md

> **Review status:** `SCAFFOLD` · last touched [YYYY-MM-DD] · tracker: `REVIEW_LOG.md`

# [Project Name] — Build Spec

> Operational detail for [Project Name]. Intent lives in `INTENT_SPEC.md`.

## Pipeline

[Empty; grows as the build takes shape]

## Tech Stack

[Empty]

## Open Questions

[Empty]

COCKPIT.md

> **Review status:** `SCAFFOLD` · last touched [YYYY-MM-DD] · tracker: `REVIEW_LOG.md`

# [Project Name] — Cockpit

*All the knobs, levers, and controls for [Project Name].*

> **How to use this:** Scan for what you want to change, then tell the agent which settings to use.

## Big Levers

| Lever | What it does | Keywords |
|-------|--------------|----------|
| [Lever 1] | [Effect] | [Keywords] |

README.md (software projects only)

> **Review status:** `SCAFFOLD` · last touched [YYYY-MM-DD] · tracker: `REVIEW_LOG.md`

# [Project Name]

[One-sentence description]

## Quick Start

[Empty; filled as soon as there is a way to run it]

Step 6 — Post-creation report

Print:

✓ Created Projects/[Name]/
  Files:
    - ORIENTATION.md
    - INTENT_SPEC.md (UNOFFICIAL)
    - TODO_[Name].md
    [- other files created]

Reminders (owner-only actions — skill won't do these):
  1. Review INTENT_SPEC.md → edit → remove UNOFFICIAL header when ready
  2. Add to STATE_OF_SECOND_BRAIN.md Tier [N] table (if Tier 1–3)
  3. Consider adding a line to MEMORY.md if this project needs cross-session memory

Hard Rules For This Skill

• Never rename files or folders. Folder name must preserve the owner's exact capitalization (e.g., My_Project not my-project).
• UNOFFICIAL marker is the promote gate. It must appear verbatim as shown in the INTENT_SPEC template; removing it is how the owner ratifies the spec as OFFICIAL.
• Do not auto-update orientation docs. INTELLECTUAL_LANDSCAPE.md and STATE_OF_SECOND_BRAIN.md are owner-authored. Skill prints reminders instead.
• Never overwrite. If the target folder exists with content, abort.
• Preserve the owner's language. Paste interview answers verbatim into the relevant sections. No paraphrasing.
• File-creation rule (Second Brain CLAUDE.md). Present the full scaffold plan → ask Y/N → wait for explicit Y before writing. This applies once per invocation, after the interview, before any Write call.

Anti-Patterns

• Don't run the interview and write in the same turn. Confirmation step is a hard gate.
• Don't assume tier. Always ask — a Tier 5 parked project gets different handling than Tier 1.
• Don't skip type. Type controls which extras appear; guessing wastes files.
• Don't substitute ORIENTATION.md with only INTENT_SPEC.md. Both always exist — they serve different purposes (narrative framing vs declarative intent).

Examples

Example invocation

User: "Let's start a new project — My_Campaign, a campaign to enter a competition, active Tier 1, rich scaffold."

Skill:

1. Asks Round A confirming name / type=campaign / tier=1 / richness=rich
2. Asks Round B gathering intent paragraph, core bullets, done criteria, related projects
3. Confirms with summary + Y/N
4. Creates Projects/My_Campaign/ with ORIENTATION + INTENT_SPEC (UNOFFICIAL) + TODO + CLAUDE + DESIGN + BUILD_SPEC
5. Prints post-creation reminders