octopus-workflow/core/skills/project-kickoff/SKILL.md

---
name: project-kickoff
description: >
  Use ONLY when the user asks about project setup, kickoff, or project
  initialization ("kickoff", "project setup", "项目初始化", "项目配置").
  Provides guidance on the octopus project kickoff workflow: checking readiness,
  running /kickoff or octopus kickoff, configuring codegraph, and understanding
  project scaffolding. Do not use for application-level configuration —
  this skill covers the octopus project lifecycle, not user application code.
triggers:
  # High-discrimination phrases only ([org-internal #4525]): bare "setup"/"init"/"配置" fire
  # on any configuration mention, and the skill gate folds the previous
  # assistant turn on approval turns — one stray "配置" in a reply re-fires
  # the gate every turn. Keep triggers to phrases that name THIS workflow;
  # generic setup/init questions still route via the description in the
  # skills listing.
  - kickoff
  - project setup
  - 项目初始化
  - 项目配置
role: Producer
---

> Core 中立版（Increment 6a 改写，原 deferHard verbatimDir）。机制、结构与 frontmatter 保持；实例术语（工具名、路径、工单号）按 `core/adapters/TERMINOLOGY.md` 绑定到具体实例。
# Project Kickoff

## 1. Overview

Project kickoff is the octopus project initialization workflow that gets a project from zero to fully configured in one command. It covers readiness detection → setup → scaffold → config → codegraph init → skills overlay pull, producing a project that is ready for the full SDLC pipeline without manual configuration steps.

## 2. When This Skill Activates

This skill activates when the user's text matches any of the trigger keywords:

- `kickoff` — asking about the `/kickoff` command or the kickoff workflow
- `project setup` — asking how to set up a project in octopus
- `项目初始化` / `项目配置` — asking how to initialize or configure an octopus project (Chinese)

Generic "setup"/"init"/"配置" mentions are deliberately NOT triggers ([org-internal #4525]): they collide with everyday configuration talk, and the hard skill gate folds the previous assistant turn into its match text on approval turns — a passing "或配置x: false" in a reply would re-fire the gate every turn. `/init` note: `/init` generates AGENTS.md via LLM; kickoff uses the managed template from `octopus setup` — the Builder distinguishes based on context.

Typical user intents include: encountering a readiness prompt at session start, wondering how to initialize a project, or wanting to understand the kickoff workflow steps.

## 3. Prerequisites

Before kickoff can run:

- `codegraph` CLI must be installed and on `$PATH` (covered by the `codegraph-setup` skill)
- Global octopus config (`<config-home>/octopus/octopus.jsonc`) must be merged and valid
- The project root must be identified (the directory octopus is running in)

### CI Readiness

After kickoff completes, check for CI configuration:

```bash
ls .gitea/workflows/ .github/workflows/ 2>/dev/null || echo "[GAP: no CI workflows]"
```

If no workflows exist, recommend creating `.gitea/workflows/ci.yml` (this repo
uses Gitea Actions) — or `.github/workflows/ci.yml` for a GitHub-hosted project
— with at minimum: typecheck, lint, and test gates. Without CI, every merge is a
manual gate — type errors, lint regressions, and test failures can land on
main and go undetected until the next local checkout.

## 4. Workflow

The kickoff workflow runs in four automated steps:

1. **Check readiness** — Determine if the project needs setup. Run `checkReadinessWithGitea()` or `octopus kickoff --check-only` to inspect the current state.
2. **Run kickoff** — Execute `/kickoff` from the TUI or `octopus kickoff` from the terminal.
3. **What happens** — A Phase 0 gate, then five sequential phases:
   - Phase 0 — **Gitea auth check**: derives the `gitea` block from the git remote origin (persisting missing fields), then verifies the token (`GET /user`) and runs the auth wizard on failure; never aborts kickoff
   - [1/5] **Setup** — Creates project directories and writes `AGENTS.md` from the managed template
   - [2/5] **Scaffold** — Creates the `<instance-root>/` skeleton (`core/skills/` directory + default `octopus.jsonc` template if absent); domain skills content arrives via the [5/5] overlay pull
   - [3/5] **Config stub + MCP wiring** — Writes the `mcp.codegraph` block into `octopus.jsonc`
   - [4/5] **Codegraph init** — Initializes and builds the per-project `.codegraph/` index
   - [5/5] **Skills remote + overlay pull** — Opt-in semantics ([org-internal #4370]); branches by flags when no `overlay.remotes` entry is configured:
     - no flags (interactive run) — **safe default**: nothing is written; a remediation hint is printed (pass `--skills-remote`, or edit `overlay.remotes`), and the readiness skills item stays not-ready
     - `--yes` — legacy behavior kept: writes the default skills remote, then pulls domain skills content (`octopus skills pull` equivalent)
     - `--skills-remote <owner/repo>` (+ optional `--skills-remote-base-url <url>`) — writes the specified remote instead (ref `main`; base URL defaults to `<instance-base-url>`), then pulls from it
     - `overlay.remotes` already configured — the write is skipped (idempotent; an explicit `--skills-remote` is ignored with a warning)
4. **Post-kickoff verification** — Run `octopus kickoff --check-only` again. After a `--yes` or `--skills-remote` run it reports all 5 items as ready; after a no-flag interactive run it reports 4 of 5 — the skills item stays not-ready until a remote is configured (`--skills-remote`, `--yes`, or a manual `overlay.remotes` edit + `octopus skills pull`).

### First-ticket hint ([org-internal #3061])

For a brand-new project still validating its concept, open the FIRST ticket as
`Kind/MVP` — the interactive no-pipeline mode (decision log + debt register in
the ticket body). It graduates by relabeling to `Kind/Feature` (analyze-dag
backfill mode picks up the decision log) when a second session, an external
contract, or a second consumer of a shared type appears. Do not route early
concept work into the full pipeline "to be safe" — the pipeline's coordination
machinery is cost, not quality, at zero coordination.

## 5. Re-kickoff / Idempotency

Re-running kickoff on an already-configured project is safe — every step is idempotent:

- **Setup** skips existing directories
- **Scaffold** skips existing files
- **Config mutation** is a no-op if the `mcp.codegraph` block already matches
- **Codegraph** re-indexes (rebuilds the graph, which is a safe refresh)
- **Skills remote** ([5/5]) skips the write when `overlay.remotes` is already configured

**Idempotent silence** (REQ-F-005): A fully configured project produces zero startup prompts. Users can run `/kickoff` or `octopus kickoff --check-only` at any time for explicit readiness checks without side effects.

## 6. Troubleshooting

Common issues and their resolutions:

- **`codegraph: command not found`** — Run the `codegraph-setup` skill, or install via `bun add -g @colbymchenry/codegraph`
- **Permission denied** — Check project directory ownership and write permissions
- **Partially complete state** — Re-run `/kickoff`; idempotent steps will complete the missing parts without affecting already-completed steps
- **MCP tools not available** — Verify `mcp.codegraph` exists in `octopus.jsonc`; re-run `octopus kickoff` to write it

## 7. Related Commands

- `/init` — Generates `AGENTS.md` using an LLM (custom, context-aware); kickoff uses the managed template from `octopus setup`
- `octopus setup` — Creates directories + `AGENTS.md` from the managed template; kickoff calls this internally
- `octopus scaffold` — Creates the `<instance-root>/` skeleton (`core/skills/` directory + default `octopus.jsonc` template if absent); run `octopus skills pull` to fetch domain skills content; kickoff calls this internally
- `octopus kickoff --check-only` — Readiness check only, no pipeline execution
- `octopus kickoff --skills-remote <owner/repo>` — Explicit opt-in: writes the given skills remote to `overlay.remotes` (ref `main`) and pulls it instead of the default
- `octopus kickoff --skills-remote-base-url <url>` — Base URL for `--skills-remote` (requires it); defaults to `<instance-base-url>` when omitted
- `octopus kickoff --yes` — Skips the opt-in confirmation and keeps the legacy behavior of writing the default skills remote (`Octopus/octopus-skills`)
- `codegraph-setup` skill — For installing the codegraph CLI and initializing the per-project index

## 8. Reference

- `<harness-package>/src/project-kickoff/readiness.ts` — `checkReadiness()` implementation (sync 4-item base)
- `<harness-package>/src/project-kickoff/readiness-gitea.ts` — `checkReadinessWithGitea()` composed 5-item check (adds gitea auth reachable)
- `<harness-package>/src/cli/cmd/kickoff.ts` — `/kickoff` command handler
- `core/skills/codegraph-setup/SKILL.md` — CodeGraph setup skill
- Project roadmap at `.artifacts/project-kickoff/` (deprecated — now stored as wiki page `project-kickoff/roadmap/` via `wiki 读写 API（见 TERMINOLOGY）`)