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锛塦)