kb-new - SKILL.md Agent Skill

name: kb-new description: Create a new Cline Kanban project from scratch — `git init` a new repo if needed, drop a starter README.md, make the initial commit, and register it as a Cline Kanban workspace. Works in any directory under ~/Dev/ (or wherever the user specifies). Uses `--no-verify` on the initial commit only if pre-commit hooks block (most new empty projects have nothing to flag, so it shouldn't come up). Use when the user says "kb-new", "new kanban project", "make a new project", "create a project for X", or wants to start a fresh Cline Kanban workspace. category: execution runtimes: [claude] pii_safe: true

Cline Kanban New Project Skill

Bootstraps a new Cline Kanban workspace from nothing: directory + git repo + initial commit + workspace registration.

Project-agnostic. Works for any new project (a new tool, a new experiment, a new client engagement). Cline Kanban auto-registers any git repo when its path is first passed to task create --project-path, so the project comes online the moment its first task is created.

When to use

Triggers: /kb-new, "kb-new", "new kanban project", "create a new project", "make a project for X", "init a project and register with kanban".

Don't use this for projects that already exist — for those, just call /kb-do --project <path> ... and Cline Kanban auto-registers on the first task. This skill is specifically for fresh, empty starts.

Inputs

Required: project name (used as both directory name and starter title)
Optional flags:
- --path <dir> — explicit parent dir (defaults to ~/Dev/)
- --description "<text>" — short description for the README and the starter task
- --with-task — create a starter Cline Kanban task after init (default: skip; just register on next kb-do call)
- --remote <url> — set git remote origin (default: none)
- --private — generate a .gitignore with strict defaults

Procedure

Resolve project path.
- If user gave --path <dir>, project path = <dir>/<name>.
- Otherwise, default = ~/Dev/<name>.
- Expand ~, normalize.
Check for collision. If the path already exists:
- If it's already a git repo with a .git/ dir, surface this and ask the user whether to (a) re-register it with Cline Kanban or (b) abort.
- If it exists but isn't a git repo, ask whether to git init in place or abort.
Create directory if needed: mkdir -p <project-path>.
Initialize git:
```
cd <project-path>
git init -b main
```
Use -b main to default to main (matches user's project layout).

Drop a starter README.md with frontmatter-free content:

# <project-name>

<description from --description, or "TBD: project description">

Created: <today, YYYY-MM-DD>

(Optional) Drop a .gitignore if --private was passed. Defaults: .env, .env.*, *.log, node_modules/, __pycache__/, .venv/, dist/, build/, .DS_Store.
Make the initial commit. Try a normal commit first:
```
git add README.md .gitignore  # only files that exist
git commit -m "Initial commit"
```
- If pre-commit hooks () block: rerun with --no-verify. New empty projects have nothing for to flag, but if the user has a global hook that runs lint/test on commit, those can spuriously fail on an empty repo. --no-verify is fine here because the commit is just an empty-project marker.
- Never re-run with --no-verify for a project with substantive content without telling the user first.
(Optional) Set git remote if --remote <url> was passed:
```
git remote add origin <url>
```
Don't push automatically. The user pushes when they're ready.
Register with Cline Kanban. Two options:
- --with-task flag: Create a starter task using kbd (the kb-do CLI wrapper):
```
kbd --project <project-path> --start "Set up <project-name>: <description>"
```
  This registers the workspace AND gives the user a first ticket to start working from.
- Default (no flag): No task created. The workspace will auto-register the first time the user runs /kb-do --project <project-path> .... Print a hint with the next-step command.
Confirm. Print:
- Project path
- Git status (branch, initial commit hash)
- Cline Kanban workspace status (registered now via --with-task, or pending first task)
- The Cline Kanban URL: http://:3000/
- Suggested next command (e.g., kbd --project <path> "first task")

Implementation reference

Run via Bash, in this order:

PROJ_NAME="<name>"
PROJ_PATH="${HOME}/Dev/${PROJ_NAME}"  # or --path-derived

# 1. Check & create
[ -e "$PROJ_PATH" ] && { echo "exists, aborting or asking"; exit 1; }
mkdir -p "$PROJ_PATH"
cd "$PROJ_PATH"

# 2. git init
git init -b main

# 3. README + (optional) .gitignore
cat > README.md <<EOF
# ${PROJ_NAME}

<description or "TBD">

Created: $(date +%Y-%m-%d)
EOF

# 4. Initial commit (try normal first, fall back to --no-verify if hooks block)
git add -A
if ! git commit -m "Initial commit" 2>/tmp/commit-err; then
  echo "Hook blocked initial commit; retrying with --no-verify (empty project, safe)"
  git commit --no-verify -m "Initial commit"
fi

# 5. Optional remote
[ -n "$REMOTE" ] && git remote add origin "$REMOTE"

# 6. Register with Cline Kanban (only if --with-task)
if [ "$WITH_TASK" = "1" ]; then
  kbd --project "$PROJ_PATH" --start "Set up ${PROJ_NAME}: ${DESCRIPTION:-initial scaffolding}"
fi

--no-verify policy

is the user's pre-commit hook system. It exists to catch real problems (secrets, broken builds, etc.) before they hit the repo.

Rules:

Default: try without --no-verify. Run the normal commit first.
Fall back to --no-verify only when:
- The repo is brand new (just created in this skill run)
- The commit has zero or near-zero content (only README + .gitignore)
- The hook failure is clearly false-positive (e.g., a lint hook complaining about no source files yet)
Never --no-verify silently. Always print "Hook blocked initial commit; retrying with --no-verify (empty project, safe)" so the user sees it.
For non-trivial commits in an existing project, never auto-fall-back. Surface the hook error and ask.

Anti-patterns

Do NOT git add . in a directory the user already had files in without confirming.
Do NOT push to a remote automatically. User pushes when ready.
Do NOT register a workspace without telling the user the next-step command.
Do NOT create a starter task by default (--with-task is opt-in) — sometimes the user just wants the scaffolding.
Do NOT init in /, ~, or any path the user didn't specify or default to.

Companion skills

/kb-do — implementation tickets with model selection
/kb-plan — planning tickets (Opus + plan mode)
/kb-status — show current board state for a project
/kb-trash — clean up tasks
/kb-link — link tasks for dependencies
/kanban — passcode + service management for the Cline Kanban server itself