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

name, description, triggers, role

name	description	triggers	role
project-kickoff	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.	kickoff project setup 项目初始化 项目配置	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:

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）)