SuperAPI AI Directory

project-init

General & other

View repository

Updated 11-06 16:15

About this skill

Project Init

One-time project setup for AI-agent management. The skill goes through a guided interview, checks what already exists, does not overwrite others' work, and creates only what is missing.

Phase 0 — Setup menu (FIRST action)

The skill starts with the menu. Wait for the user's explicit choice — no actions before that.

Show the user:

Что настраиваем? Отметь нужное:

☐ 1. Локальные файлы — tasks.md · okr.md · decisions.md · AGENTS.md или CLAUDE.md (config block)
☐ 2. Настройка GitHub — Project + labels + список репо

«всё» = обе опции

If the user chose "everything" or "1, 2" — run both branches in order (first 1, then 2). If only one was chosen — skip the second entirely in all phases.

Do not act until there is an answer. This is the first and only action of Phase 0.

Phase 1 — What already exists (verify, only for the selected option)

Goal: before the interview, find out what exists, so as not to ask unnecessary questions and not overwrite others' work.

If option 1 is selected — Local files

# Базовая папка проекта (стандарт: 0_hq/, но может быть любой)
ls -la 0_hq/ 2>/dev/null || echo "0_hq нет"

# Канонические файлы
for f in tasks.md okr.md decisions.md; do
  if [ -f 0_hq/$f ]; then echo "✓ 0_hq/$f"; else echo "— нет 0_hq/$f"; fi
done

# AGENTS.md / CLAUDE.md — для config block
# Используем тот что existing. Если оба есть — primary тот что не симлинк.
# Если ни одного — спросим в Phase 2 какой создать (по типу агента).
for f in AGENTS.md CLAUDE.md; do
  if [ -L 0_hq/$f ]; then echo "↪ 0_hq/$f → $(readlink 0_hq/$f)"
  elif [ -f 0_hq/$f ]; then echo "✓ 0_hq/$f ($(wc -l < 0_hq/$f) строк)"
  else echo "— нет 0_hq/$f"
  fi
done

# Если AGENTS.md или CLAUDE.md существует — есть ли уже config block?
grep -lA 5 "Agent Operations Config" 0_hq/AGENTS.md 0_hq/CLAUDE.md 2>/dev/null

# Если okr.md существует — какой период?
head -10 0_hq/okr.md 2>/dev/null

Record in the session: what already exists, what is missing. In the following phases, ask questions only about what is missing.

If option 2 is selected — GitHub

# Какой github username?
gh api user --jq '.login'

# Существующие projects пользователя
gh project list --owner <username>

# Существующие репо
gh repo list <username> --limit 30 --json name,description

# Если знаем репо проекта — существующие labels
for repo in <repos>; do
  gh label list -R $repo --limit 50 | grep -iE "retro|epic|backlog|^W[0-9]"
done

Record: whether a suitable Project exists, which labels have already been created, which repos are in scope.

Phase 2 — Interview (one question at a time, only for gaps)

Rules:

  • One question at a time — do not overwhelm
  • Do not ask about what exists — if the file/config already exists, skip it in the interview
  • Record each answer immediately — do not keep it in your head

If option 1 is selected — Local files

1.1 Project base folder

Only if the folder does not exist.

"In which folder should the canonical files be kept? By default 0_hq/.»

1.2 Business context

Only if neither AGENTS.mdnor CLAUDE.md exists, or neither of them has a config block.

"What do you do? Business type, solo or with a team?" "What products/services do you sell? Prices, where they live (landing page, bot, etc.)"

If none of the files exist, additionally ask:

"Which agent is the main one — Claude Code or Codex/another? The file name depends on this: CLAUDE.md for Claude Code, AGENTS.md for the universal one. You can create both and link them with a symlink — but usually one.

1.3 OKR / North Star (only if okr.md is missing or the period is outdated)

If the file exists and the period is current — skip, just relink it in config.

1.3.a — Period and North Star

"What horizon are we setting goals for? (Q2 = quarter / H2 = half-year / 2026 = year)" "Formulate the North Star in one sentence: by the end of the period you/we will have ___.".

Anti-pattern: if the answer starts with "increase X by Y%" — that's a KR, not a North Star. Clarify: "And what will you have when X grows by Y%? That's the North Star.".

1.3.b — Objectives (1-3 per period)

"What 1-3 major directions need to move for the North Star to become reality?"

Ask one at a time. Per O also:

  • Name (short — 3-7 words)
  • Why one sentence of motivation

Anti-pattern: 4+ Objectives per quarter for a founder-of-one. STOP, ask to cut down to top-3.

1.3.c — Key Results (2-4 per each Objective)

Per O ask 2-4 KRs. Per KR:

"How will we know that O is moving? (a) by date X there is Y — binary, or (b) metric Z reached N — numeric" "Where will this be measured? A concrete path — file, sales.db query, GitHub issue, dashboard.".

Anti-pattern: KR without a source-of-truth pointer. STOP, ask "where will we measure?". Without a pointer the KR turns into hot air.

1.3.d — Guard rails (optional)

"Which metrics do you want to monitor as guard rails — not to reach, but to keep within normal range? For example \"revenue/week ≥ $X\" or \"outbound share ≥ N per week\". This is protection against Goodhart's law: KRs can be gamed, guard rails catch the skew."

Can be skipped if the user isn't ready.

1.3.e — Cadence

"When do we review OKRs? By default — in weekly-retro Phase 1.5 (weekly progress) + monthly snapshot. Sound good?"

If option 2 is chosen — GitHub

2.1 Repos

If the repos aren't defined yet.

"Which repos belong to this project? Take 5-7 key ones for weekly operations, we'll connect the rest later. Categorize: execution / growth / infrastructure."

For each repo, ask for the category (one of three).

2.2 Project

If the Project already exists — ask:

"Use <Project N> (found in gh project list) or create a new one?"

If not:

"Project name? For example \"Personal Corp\" or \" ops\"."

2.3 Routing

"Which tasks go to which repo? Pattern → repo. For example: \"bot, broadcast\" → hsl-mozg, \"lessons\" → teach-vibecoding."

Minimum 3 routing rules. Can be extended later.

Phase 3 — Creation (per selected only)

Option 1 — Local files

3.1.a Create the structure

mkdir -p <project-folder>/retros/

# Stubs — НЕ overwrite existing
[ ! -f <project-folder>/tasks.md ] && touch <project-folder>/tasks.md
[ ! -f <project-folder>/decisions.md ] && touch <project-folder>/decisions.md

# AGENTS.md / CLAUDE.md — файл инструкций для агентов.
# Логика: используем тот что existing. Если ни одного — создаём по выбору пользователя из 1.2.
# Симлинк второго на первый — опционально, если пользователь явно попросил.
AGENT_FILE="<выбран в 1.2 или existing из Phase 1>"  # AGENTS.md либо CLAUDE.md
[ ! -f <project-folder>/$AGENT_FILE ] && touch <project-folder>/$AGENT_FILE

Fill the files with minimal templates (do not fabricate data).

3.1.b tasks.md template

# Задачи

Обновлено: <date>
Протухает после: <date + 7 дней>

## Сейчас (W{NN})

| Приоритет | Работа | Почему | Источник |
|---:|---|---|---|
| 1 | ... | ... | ... |

## Решения недели

(заполняется в weekly-planning)

## Не сейчас

- ...

3.1.c okr.md template (with user input from 1.4)

# OKR

Обновлено: <date>
Период: <Q2 2026 / H2 2026 / etc>

## North Star

<aspirational sentence из 1.3.a>

## Objectives

### O1: <название из 1.3.b>

**Why:** <motivation>

**Key Results:**
- **KR1.1** — <формулировка из 1.3.c> · source: <path/query/issue>
- **KR1.2** — <...> · source: <...>

### O2: <...>

## Guard rails

(из 1.3.d, если есть)
- <metric>: floor ≥ X · source: <...>
- <metric>: ceiling ≤ Y · source: <...>

## Cadence

Review: <из 1.3.e>

---

## История

<append-only когда период закроется>

Anti-pattern: creating okr.md without user input per 1.4. If the user skipped — do NOT generate an empty file with placeholders. Show that generation was skipped.

3.1.d Config block

Write to the file from the variable $AGENT_FILE (AGENTS.md or CLAUDE.md). If the file exists with content — ADD the block at the end, do NOT overwrite.

## Agent Operations Config

### Канонические файлы
canonical:
  tasks: <path>/tasks.md
  okr: <path>/okr.md
  decisions: <path>/decisions.md

### Weekly cadence
weekly_cadence: <день недели — главный delivery>
retro_log_path: <path>/retros/

### Repos (если выбрана опция 2)
repos:
  - owner/repo-1   # execution — что делает
  - owner/repo-2   # growth — что делает
  - owner/repo-3   # infrastructure — что делает

### GitHub Project (если выбрана опция 2)
project_id: <N>
owner: <github-username>

### Task routing (если собирали в 2.3)
routing:
  - pattern: "bot, broadcast"
    repo: owner/bot-repo
  - pattern: "content, lessons"
    repo: owner/content-repo

Option 2 — GitHub setup

3.2.a Project (if new)

gh project create --owner <owner> --title "<name>"

Then add custom fields via UI or API:

  • Status (single-select): Todo / In Progress / Review / Done
  • Deadline (date)
  • Week (single-select): W1, W2, ... W52 — for retro/planning

3.2.b Labels in each repo

for repo in <repos>; do
  gh label create "retro:W00" -R $repo --color "D4C5F9" \
    --description "Шаблон лейбла недельного ретро"
  gh label create "epic" -R $repo --color "5319e7" \
    --description "Длинный трек, не недельная задача"
  gh label create "backlog" -R $repo --color "ededed" \
    --description "Отложено вне retro-цикла"
done

The current retro week (retro:W{NN}) is created separately at the first retro via weekly-retro skill.

3.2.c Repos в config block

If option 1 is not selected — create a minimal agent file (AGENTS.md or CLAUDE.md depending on the agents type) with only repos + project + routing. If option 1 is selected — this block has already been created in 3.1.d, just fill in repos / project / routing.

Phase 4 — Verification

Option 1

# Канонические файлы существуют
ls <path>/tasks.md <path>/okr.md <path>/decisions.md
ls -l <path>/AGENTS.md <path>/CLAUDE.md 2>/dev/null   # один или оба, симлинк показывает →

# Config block (в любом из двух)
grep -lA 5 "Agent Operations Config" <path>/AGENTS.md <path>/CLAUDE.md 2>/dev/null

# OKR sanity-check
head -25 <path>/okr.md

Show the results to the user. If something is missing — report it and offer to fill it in.

Option 2

# Project существует
gh project list --owner <owner> | grep "<project-name>"

# Labels в каждом репо
for repo in <repos>; do
  echo "=== $repo ==="
  gh label list -R $repo | grep -E "retro|epic|backlog"
done

What's next

After init, the following work:

  • manager — sync session work to GitHub issues (requires option 2)
  • weekly-retro — structured retro (requires option 1, optionally 2)
  • weekly-planning — week plan (requires option 1)
  • pm-metrics — metrics review with OKR alignment check Step 7 validates what was generated in 1.4

Each skill reads the config block from CLAUDE.md — no reconfigure needed.

Red flags — STOP

  • Existing AGENTS.md or CLAUDE.md with content → ADD config block at the end, do not overwrite
  • BOTH files exist as separate regular files (not a symlink) → STOP, ask which is primary; the second can be left as is or made a symlink to the first
  • Existing GitHub Project → ask "use or create a new one?"
  • Existing okr.md с current period → ask "update or import as is?"; do not overwrite silently
  • User does not use GitHub → option 2 is skipped, local files work on their own
  • KR without a source-of-truth pointer (path / sales.db query / issue) → STOP, ask "where will we measure?"
  • 5+ Objectives per quarter → STOP, founder-of-one fit = 1-3 O. Ask to cut down
  • North Star = "increase X by Y%" → that's a KR, not an NSM. Clarify "and what will you have when X grows?"
  • Launching Phase 1+ without an explicit answer to the Phase 0 menu → STOP, wait for the choice

Anti-patterns

  • Ask everything at once — overcomplication, the user gets lost. One question at a time
  • Overwrite existing files — silent data loss. Always check + append/extend
  • Auto-generate okr.md with placeholders — fabrication for the sake of a "complete artefact". Better to skip the OKR option
  • Create labels in ALL of the user's repos — overkill. Only in the repos specified in option 2
  • Ignore the answer to the menu — Phase 0 is the only action before the choice, do not launch Phase 1 "just in case"

Frequently asked questions

"I have 20+ repos" — pick 5-7 that matter for weekly operations. We'll connect the rest later with a separate run of the skill.

"The project structure is messy" — that's fine. Init creates a clean layer on top, no need to reorganize the existing stuff.

"I already have OKRs in a Google Doc" — in option 1.4 choose "already have, importing" — the skill will ask you to paste the contents and save them to okr.md with minimal normalization.

"Can I run the skill a second time to add only OKRs?" — yes. Phase 0 menu → select only option 1 → Phase 1 verify will show that existing → Phase 2 will ask only about OKR (the rest is skipped) → Phase 3 will create only okr.md.

Related skills

  • weekly-retro — fills the outcomes scorecard based on KRs from okr.md
  • weekly-planning — turns KRs into weekly outcomes
  • pm-metrics — Step 7 validates OKR alignment, Step 2 decomposes North Star → L1 → L2
  • manager — syncs session work to GitHub issues, uses repos / labels from config